Skip to contentSkip to navigationSkip to topbar
Figma
Star

Data Grid

Version 8.3.1GithubStorybookPeer review pending

A data grid is an interactive table used for working with a large collection of data in a scannable way.

Component preview theme
const StandardDataGrid = ({element = 'DATA_GRID'}) => {
return (
<DataGrid aria-label="User information table" striped>
<DataGridHead >
<DataGridRow >
<DataGridHeader>{TableHeaderData[0]}</DataGridHeader>
<DataGridHeader>{TableHeaderData[1]}</DataGridHeader>
<DataGridHeader>{TableHeaderData[2]}</DataGridHeader>
<DataGridHeader>{TableHeaderData[3]}</DataGridHeader>
<DataGridHeader>{TableHeaderData[4]}</DataGridHeader>
</DataGridRow>
</DataGridHead>
<DataGridBody>
{TableBodyData.map((row, rowIndex) => (
<DataGridRow key={"row-" + rowIndex}>
{row.map((col, colIndex) => (
<DataGridCell key={"cell-" + rowIndex + "-" + colIndex}>
{col}
</DataGridCell>
))}
</DataGridRow>
))}
</DataGridBody>
</DataGrid>
);
};
render(
<StandardDataGrid />
)

Guidelines

Guidelines page anchor

About Data Grid

About Data Grid page anchor

The Data Grid is an enhanced Table component. It can be used to improve the way users scan and interact with tabular data. It can be used alongside other components in Paste to provide the following functionality:

  • Full keyboard navigation
  • Responsive horizontal scrolling
  • Column sorting
  • Editable cells
  • Selectable rows
  • Pagination

Semantics

Semantics page anchor
  • The DataGrid component uses HTML table elements rather than div elements. This provides better screen reader support.
  • The DataGrid table element has role="grid" applied.
  • The DataGrid table element has an aria-label provided.
  • The DataGridRow tr element has role="row" applied.
  • The DataGridRow tr element has an aria-selected provided.
  • Column headers with sorting list the direction with the aria-sort attribute.

The data grid can be in two navigational modes: Actionable and Navigational. Each has different requirements listed below:

Navigational: page anchor
  • The data grid has one tab stop. This means if you press the [Tab] key to enter the data grid, the next [Tab] key press will take you to the first element outside the data grid.
  • Data cells can be focused using standard navigation keys, including directional arrows, [Home], [End], [Control+Home], [Control+End], [Page up], and [Page down].
  • Tabbing out of the table and back into the table will restore focus to the last selected data cell.
  • Pressing the [Enter] key will swap the user into the Actionable mode. If there’s a focusable child element in the current cell, it will gain focus.
  • Data grid cells lose the ability to focus. However, focusable elements inside each cell regain their tabindex.
  • The user can [Tab] through all the focusable elements in the table.
  • Pressing the [Escape] key returns the user to Navigational mode, and moves the focus to the closest parent cell.
  • When interacting with a component in a cell that also uses the [Escape] key, the user will need to press the [Escape] key twice to return to Navigational mode.

Data grid with custom cell content

Data grid with custom cell content page anchor

This example shows the composition of Paste components like Input and Select in the cells. Notice how the tabIndex is correctly managed without any additional code.

Data grid with selectable rows

Data grid with selectable rows page anchor

Row selection is achieved with the CheckboxGroup and Checkbox components and the selected prop on DataGridRow.

Data grid with sortable columns

Data grid with sortable columns page anchor

This package exports a DataGridHeaderSort component which render the UI for a sort button in the DataGridHeader. Please be mindful to correctly set the aria-sort attribute on the DataGridHeader component.

Data grid with pagination

Data grid with pagination page anchor

It is not ideal to display more than a few rows at a time (consider 10 as a default), so the Pagination component is used to handle multiple pages of information.

Data grid in a loading state

Data grid in a loading state page anchor

Rather than using a Spinner component, you can use the Skeleton Loader in the cells to create a more pleasant loading experience.

The Data Grid inherits from the Table component, so you can take advantage of all the same layout techniques found in the Table examples to control how your Data Grids render on the page.

This example combines all the separate features displayed previously into one example. It shows how all the features work together harmoniously through composition.

To internationalize an data grid, simply pass different text as children to the data grid sub-components. The only exceptions to this are the labels for the DataGridHeaderSortIcon component. To change the label of a sorting icons, use the matching i18n prop for the direction. For an ascending variant, for example, set the i18nAscendingLabel prop.

The Data Grid component was designed to be accessible and composable. This means it can adapt to any of your product and development needs while providing an inclusive experience for all of your users.

This package provides the following component exports, which correspond closely to HTML table element naming:

  • DataGrid
  • DataGridHead
  • DataGridRow
  • DataGridHeader
  • DataGridHeaderSort
  • DataGridBody
  • DataGridCell
  • DataGridFoot

You are free to put any Paste component in the Data Grid cells and it should just work. Keep in mind that anything that dynamically updates an element's tabIndex value may fail to work correctly.

If the Data Grid can’t show data yet (for example, it’s in a draft state), leave cells blank.

If the data underlying the Data Grid is active but the value for the cell is zero, show 0 in the cell.

If a piece of data is missing because the metric in a certain column does not apply to a given row, show “N/A” and use the HTML abbreviation element to communicate the full meaning of the abbreviation (“Not applicable”). This ensures any customers using assistive technologies will understand the cell entry.

Avoid documenting an entire error message within a row. Use an indicator, like an icon or an icon with a short message. The short message can be displayed in a Popover on the icon, or in a cell. Then use other methods, like a Popover, Side Modal, or full page to communicate complete error and resolution information.

When multiple errors affect a single row, indicate the number of errors and provide specific error and resolution information within a Popover, Side Modal, or full page.

When an error(s) affects an entire column, consider an indicator near the column header with additional information available in a popover or other component.

When all data in a Data Grid does not load, show an error empty state.

(information)

Don't forget about the Table component

If the data is static and doesn't need sorting, prefer to use a Table component which is more lightweight.

Do

Use data grid for interactive, tabular data

Don't

Don't use data grid for static data