DataTable

Interface of DataTable
🏗 Coming Soon

The <DataTable> component, like <Table>, displays tabular data. However, unlike a <Table>, a <DataTable> allows you to bake in a set of actions on each row. Common use cases include:

  • A list of users with user details and a "Delete This User" action
  • A list of groups and their associated permissions with an "Edit This Group's Permissions" action on each row
  • A list of recently run queries and a "Rerun This Query" action on each row

The <DataTable> component acts as the main wrapper to other <DataTable>-related components. It must receive an array of type DataTableColumn in its columns prop. That array should contain objects that describe the columns in your <DataTable>.

ID
Name
1Gorgonzola
2Cheddar
3Blue

DataTableItem

Interface of DataTableItem
🏗 Coming Soon

The <DataTableItem> component represents a row of data in your DataTable.

To define actions on a row, pass in <DataTableAction> elements (wrapped in a React.Fragment if there are multiple) into the actions prop.

You can also pass a callback to the onClick prop, but note that this callback will not fire when clicking on the Vertical Dots <IconButton />.

The actionsTooltip prop can be used to set the tooltip text of a row's actions button. This prop will also be used in a visually hidden label on the actions button, which is especially useful for getting the actions button DOM element when testing.

DataTableCell

Interface of DataTableCell
🏗 Coming Soon

The <DataTableCell> component is equivalent to a data cell in your DataTable. <DataTableCell> elements should always be children of a <DataTableItem> element (i.e. each row should contain some number of column elements).

In its simplest form, a <DataTableCell> element will display whatever child elements it has.

You can also create more advanced layouts within your <DataTableCell> by utilizing the optional detail and indicator props.

Passing in a React element into the detail prop will display said element underneath any child elements of your <DataTableCell>.

Passing in a React element into the indicator prop will display said element left of any child elements (and any element passed into the detail prop).

Name
Cheddar

Wikipedia

Note: By default, clicking on any element within a <DataTableCell> will trigger the onClick of the parent <DataTableItem>. To prevent this, make sure to include an event.stopPropagation() call within your <DataTableCell>'s onClick.

DataTableAction

Interface of DataTableAction
🏗 Coming Soon

The <DataTableAction> component represents an actionable item on the rows of your DataTable. As noted above, you can supply each of your rows with actions by passing <DataTableAction> elements into the actions prop of the parent <DataTableItem> element.

States

In the event that your page and <DataTable> render before data is available (i.e. before a Promise resolves), you can use the state prop to conditionally render a loading icon until your data is ready.

Passing "loading" into a <DataTable>'s state prop will render a <Spinner> icon.

Additionally, you can render a "No Results" message using the state="noResults" prop. When state="noResults" the <DataTable> will display a "No Results" message in place of its children.

To customize the "No Results" message text, use the noResultsDisplay prop. Strings will be formatted as shown below, use JSX for custom formattng if you prefer.

Name
Cheddar

Sorting

You can implement sorting on a <DataTable> by passing a function into the optional onSort prop.

Clicking on the column header will lead to an onSort call, with (1) the column's id and (2) the next sort direction, passed in as arguments. The sort direction argument will either be a string 'desc' if the current sort direction of the column is 'asc', or 'asc' in all other cases.

Note: Only columns whose corresponding column objects have canSort: true will be sortable. In addition, if your data is initially sorted on a specific column, you may want to default the corresponding column object with a sortDirection property.

The function passed into onSort, generally speaking, should perform these actions for proper sorting behavior:

  • Update the corresponding column object's sortDirection
  • Sort the collection representing your data

If you want default sorting behavior, you can use the doDefaultDataTableSort helper function. The doDefaultDataTableSort helper function will return a sorted data array as well as an updated columns array, which can then be used to replace your existing arrays post-sort.

ID
Name
1Gorgonzola
2Cheddar
3Blue

Selecting rows

You can add row select behavior on a <DataTable /> by passing a valid into the select prop.

The following properties are required in the object passed into the select prop.

  • onSelect: Clicking on a checkbox (or the row when onClickRowSelect is true) will trigger the onSelect callback, with the id of the checkbox's DataTableItem passed in as an argument.

  • onSelectAll: Callback that is triggered when the header's checkbox is clicked

  • selectedItems: An array containing the ids of all selected items. Will usually be a piece of state.

  • pageItems: An array containing the ids of all currently visible items. This is mainly used to help calculate the checked state of the header checkbox.

The following properties are optional in the object passed into the select prop:

  • onClickRowSelect: If true, clicking on a row will trigger the onSelect function.

Note: For accessibility purposes, the header checkbox is described by the ID of the header row. To set the ID of the header row, use the headerRowId prop on DataTable.

ID
Name
1Gorgonzola
2Cheddar
3Blue

useSelectManager

The useSelectManager hook can be used to quickly create the standard building blocks of DataTable select behavior.

useSelectManager accepts the following parameters:

Parameter NameTypeDescription
selectableItemsstring[]An string[] array containing the id's of all selectable items. On a paginated DataTable, this will usually only include visible item ids'.

useSelectManager returns an object with the following properties:

Return Property NameTypeDescription
selectionsstring[]A piece of state of type string[] containing the id's of all selected items. Will initially contain 0 elements.
setSelections(selections: string[]) => voidThe setter for the selections state.
onSelect(id: string) => voidA callback function that accepts a string id, and will add that string id to the selections state. Will usually be passed to a DataTable's onSelect prop.
onSelectAll() => voidA callback function that accepts no parameters, and will add all selectableItems to the selections state. Will usually be passed to an DataTable's onSelectAll prop.
ID
Name
1Gorgonzola
2Cheddar
3Blue

Control Bar

DataTable comes with a built-in control bar that allows for bulk actions and additional select control.

A DataTable will reveal its control bar when the following conditions are met:

  • The array passed into the select.selectedItems prop has length > 0.
  • A valid object is passed into the bulk prop.

The bulk prop is used to configure a DataTable's control bar. The object passed into bulk must have the following properties:

  • actions: Bulk actions that are available when one or more items are selected
  • onTotalClearAll: Callback that is triggered when the user presses the "Clear Selection" button
  • onTotalSelectAll: Callback that is triggered when the user presses the "Select all X results" button in the control bar
  • pageCount: The total number of visible items (i.e. the total number of items on the current page in paginated DataTables)
  • totalCount: The total number of items, both visible and nonvisible, in this DataTable

Note: The onSelect returned from the useSelectManager hook is designed to work seamlessly with the control bar. In the event that a user selects all items, both visible and non-visible, a follow-up click on a checkbox will unselect both the clicked item and all non-visible items.

ID
Name
1Gorgonzola
2Cheddar
3Blue
1 of 2

Truncation

DataTable plays nicely with Truncate, when you wish to condense the table and keep all values to a single line.

Title
Description
CheddarCheddar cheese is a relatively hard, off-white (or orange if colourings such as annatto are added), sometimes sharp-tasting, natural cheese. Originating in the English village of Cheddar in Somerset, cheeses of this style are now produced beyond the region and in several countries around the world.
ParmesanParmigiano-Reggiano or Parmesan is an Italian hard, granular cheese that is produced from cow's milk and has aged 12–36 months. It is named after the producing areas, the provinces of Parma, Reggio Emilia, the part of Bologna west of the Reno, and Modena (all in Emilia-Romagna); and the part of Mantua (Lombardy) south of the Po. Parmigiano is the Italian adjective for Parma and Reggiano that for Reggio Emilia.