<DataTable> component, like
<Table>, displays tabular data. However, unlike 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
<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
<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
You can also pass a callback to the
onClick prop, but note that this callback will not fire when clicking on the Vertical Dots
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> 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
Passing in a React element into the
detail prop will display said element underneath any child elements of your
Passing in a React element into the
indicator prop will display said element left of any child elements (and any element passed into the
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
<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
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
state prop will render a
Additionally, you can render a "No Results" message using the
state="noResults" prop. When
<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.
You can implement sorting on a
<DataTable> by passing a function into the optional
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
The function passed into
onSort, generally speaking, should perform these actions for proper sorting behavior:
- Update the corresponding column object's
- 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.
You can add row select behavior on a
<DataTable /> by passing a valid into the
The following properties are required in the object passed into the
onSelect: Clicking on a checkbox (or the row when
onClickRowSelectis true) will trigger the
onSelectcallback, with the id of the checkbox's
DataTableItempassed 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
onClickRowSelect: If true, clicking on a row will trigger the
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
useSelectManager hook can be used to quickly create the standard building blocks of
DataTable select behavior.
useSelectManager accepts the following parameters:
|selectableItems||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 Name||Type||Description|
|selections||A piece of state of type string containing the id's of all selected items. Will initially contain 0 elements.|
|setSelections||The setter for the selections state.|
|onSelect||A 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||A 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.|
DataTable comes with a built-in control bar that allows for bulk actions and additional select control.
DataTable will reveal its control bar when the following conditions are met:
- The array passed into the
select.selectedItemsprop has length > 0.
- A valid object is passed into 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
totalCount: The total number of items, both visible and nonvisible, in this
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.
DataTable plays nicely with Truncate, when you wish to condense the table and keep all values to a single line.
|Cheddar||Cheddar 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.|
|Parmesan||Parmigiano-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.|