Tables display tabular data in columns and rows. They organize information to enable users to navigate, view, search, sort, and edit the rows listed.

Example

Properties

"Table.TH" Component

property	propType	required	default	description
isCollapsed	bool	-	false	Tell the cell to take up the least amount of width possible. This only works well if the table layout is `auto`, not `fixed`.
isNumerical	bool	-	false	Right-align the cell if the contents are numerical
children	node	-	-	Content within the `Table.TH` component
colSpan	number	-	-	Number of columns that the cell should span
testSection	string	-	-	Hook for automated JavaScript tests
width	string	-	-	A number with a unit that becomes the width of the `Table` cell

"Table.TR" Component

property	propType	required	default	description
backgroundColor	oneOf 'faint' | 'light'	-	-	Background color for each row
borderStyle	oneOf 'bottom' | 'top' | 'sides' | 'ends' | 'none'	-	-	Border style for each row
children	node	-	-	Expects a `Table.TD` or `Table.TH` component
isActive	bool	-	-	If true, add active class
noBorder	bool	-	-	If true, add class to remove border
testSection	string	-	-	Hook for automated JavaScript tests

"Table.THead" Component

property	propType	required	default	description
children	node	-	-	Should be a `Table.TR` component
testSection	string	-	-	Hook for automated JavaScript tests

"Table.TD" Component

property	propType	required	default	description
isNumerical	bool	-	false	Right-align the cell if the contents are numerical
children	node	-	-	Content within the `Table.TD` component
colSpan	number	-	-	Number of columns that the cell should span
testSection	string	-	-	Hook for automated JavaScript tests
verticalAlign	oneOf 'middle'	-	-	Apply a class that vertically aligns the cells within the children
width	string	-	-	A number with a unit that becomes the width of the `Table` cell

"Table.TBody" Component

property	propType	required	default	description
children	node	-	-	Should be a `Table.TR` component
testSection	string	-	-	Hook for automated JavaScript tests

"Table" Component

property	propType	required	default	description
density	oneOf 'tight' | 'loose'	-	'tight'	Sets the padding within cells
tableLayoutAlgorithm	oneOf 'auto' | 'fixed'	-	'fixed'	Adjust the [CSS `table-layout` property](https://developer.mozilla.org/en-US/docs/Web/CSS/table-layout) that is used to calculate the with of inner table cells.
children	node	-	-	Should be a `Table.THead` or `Table.TBody`
shouldAddHover	bool	-	-	Whether to set the hover class on the Table
style	oneOf 'wall' | 'rule' | 'rule-no-bottom-border'	-	-	Available border and hover options
testSection	string	-	-	Hook for automated JavaScript tests

Usage

A table is used to display rows of information. Each table has a fixed number of columns, but the number of rows may vary. The data displayed in the cell of a table can be text, numeric, or have an action.

Table Sizing

Loose

Loose tables are the most common size, and are easy to read and parse. They're considered to be the default table style. Use these in all dashboards and most areas of the product.

Tight

Use tight tables when you need to display small, bite-sized pieces of information -- such as the conversion rates for a given variation -- in a compact space. Information is tightly clustered in these tables, so they shouldn't be used for dashboards or other long scrolling tables that contain a lot of information.

Considerations

Controls

Table cells may contain controls. Generally the controls follow the dialog alignment hueristic of being as far to the right as possible. Consider placing controls to the right side of the table, or in the last column.

Labeling

Table headers should be consise and clear. Each row should provide some identifier such as the name of the item listed in the table. Usually clicking the identifier allows users to edit or expose more information about that particular item.

Sorting

Make tables sortable by as many columns as possible, including columns that contain elements other than numbers or text -- such as "status." Users should be able to sort the table by status, or other indicators.

Columns that only contain controls should not be sortable by column.

Decide on a logical default column to sort by for each table. In our product, the default column is usually the "Created" column, which displays the date on which the item was created. This makes it easy for users to find the what they're looking for in the table, even when items are renamed or reordered.

Filtering

Although not a component of the table directly, a facilty to filter the table should be provided in most cases. This is espeically true for tables that contain many items.

Alignment

Align the text of numeric cells and numeric dates to the right. This makes tabular data of different lengths easier to read.

Best Practices