Data grid

In progress | Storybook link coming soon

To scan a lot of information at once and to make it easy to compare data points between rows or columns.
If the data is easy to understand when all data points are displayed in a flat hierarchy or can easily be grouped by column values.
Data needs to be edited or the rows and columns support some kind of user interaction.
To house and display a collection of objects or datasets that a user can select from to dive deeper into more complex data views.

You have a small amount of information and hierarchy matters more than column scan: consider a simple list, Tree view, or Card.
When the user switches between object views on the same page: consider Tabs or a Menu-driven view switcher.
When most cells would be empty: consider a Tree view, list, or Card instead of a sparse grid.

If the Data grid allows for filtering, sorting and grouping, make sure this functionality is included in the column headers by default with the appropriate sort icon or more options Button. In addition to this, this functionality may also surface in the page toolbar, but it should be in the column header by default.
Keep column headers short: column headers are short labels used to define the kind of data that is shown in that column.
Don’t use a single column to show multiple pieces of data: the column header should accurately represent the data point rendered in the column’s cells.

Order rows intuitively: data should be initially rendered in an intuitive order. For example, starting with the most recently created items.
Visually communicate when data is related: use expand/collapse chevrons and indentation to show nested (or child) data rows.

Keep cell content concise: cells should represent data in the shortest possible format. This makes the table easier to scan, and preserves horizontal space.
Avoid wrapping or truncating cell content as much as possible. However, when this is unavoidable, it is better to wrap content to accommodate long strings because it does not hide the content and most likely prevents horizontal scrolling over the entire table.
Content truncation may be necessary when column widths are set. The full content may be exposed in a browser tooltip.
Align content appropriately:
- Strings, Avatars, Badges → left-aligned (in left to right reading languages).
- Numbers (quantities, amounts) → right-aligned.
- Actions (icons, buttons) → center-aligned.
Help the user understand why cell data is missing: you may show a message to explain an absence of data. Avoid leaving cells blank Instead, use Not applicable or N/A in a muted color token to reduce the visual prominence, unless calling attention to missing data is imperative for the user’s task.

See Pagination section for more details.

Sorting:

Sort controls live in the column header, visible on hover. May also appear in the page toolbar, but the column header is always the default.
A sortable table must have one column sorted on load.
Click cycle: ascending → descending → unsorted. Icon persists in the first two states, disappears when unsorted.

Column reordering:

Drag columns to reorder. Can also be managed via the page toolbar, but must always be available in the column header too.

Filtering:

Filter icon appears on hover in the column header. Can also surface in the page toolbar, but must always be available in the column header — either as its own icon or under the overflow menu.

Pinning:

Triggered from the column header overflow menu. Freezes that column in place — useful when there are enough columns to require horizontal scrolling. Only one column can be pinned at a time.

Bulk action:

Use checkboxes for multi-row selection. Selecting rows highlights the row and reveals an Action toolbar at the bottom of the page — use this pattern for bulk edit or delete.
Don’t put primary action buttons in the page toolbar that depend on a row being selected — disabled states are an accessibility problem.
Clicking a row highlights the row and selects it (if Checkboxes are present). If a row opens a detail view (drawer, dialog, side panel, or new page), that must be triggered via a link in the cell, not the entire row click.

Inline actions:

Per-row actions (delete, duplicate, etc.) live in the row’s overflow menu. Never expose them as visible buttons in the row.

Pagination, Checkbox selection, Action toolbar for bulk ops, row Menu, Badge / Avatar in cells, Tooltip on truncated values.

Documentation Index