v1.0.0 | View in Storybook
When to use
- 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.
When to use something else
- 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.
Column headers
- 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 icon. In addition to this, this functionality may also surface in the Toolbar above the datagrid, 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.
Rows
- 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.
Cells
- 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.
Pagination is the standard pattern for data grids because analytical and operational workflows require explicit item location, stable scrollbar mechanics, multi-row selection, and accessible footers.
- Operators need to find specific records, navigate back to previous results, or share deep-linked page URLs (e.g., ?page=4&limit=50).
- The data grid relies on a structured footer containing total record counts, page size controls, or export actions.
- Users perform bulk operations (e.g., batch row editing, multi-select approval) where selection scopes must remain unambiguous.
- Exact spatial orientation matters (e.g., referencing “Item 12 on Page 3” in shift reports).
- Infinite scroll: Continuous observation feeds, live log streaming (e.g., telemetry logs, system event feeds), or media-heavy inventory lists where discovery takes priority over precision.
- Virtualized Scroll (Windowing): Large pre-filtered or buffered datasets (e.g., 10,000 continuous sensor readings) where users expect a native, single-scroll experience without discrete page splits, while maintaining sticky grid headers and locked footers.See Pagination section for more details.
Placement
- Make sure tables span the main content area and are left and right aligned with content above and below or share the same margin spacing.
- Left align a Toolbar and Pagination with the table if using.
- If using a Toolbar with CTAs, right align those CTAs with the table, while filter actions remain left aligned.
- Don’t ignore page margins. The left and right margins provide visual relief from visually complex and heavy data sets in a table.
Behavior
Loading
Use “skeleton” placeholders to indicate loading content. The skeleton or loading shimmer placeholder should match the real content as closely as possible. Use the following properties to adjust the size, alignment layout of the skeleton placeholder:
- column width
- alignment
- whether or not there is a leading visual
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.
Columns & rows
- Drag columns to reorder.
- Column reordering can also be managed via the Toolbar, but must always be available in the column header too.
- Users can show or hide individual columns by selecting the option from the overflow Menu. If including this functionality, you must include an option to “manage columns” as this will enable the users to return, or show, the column after it’s been hidden.
- Rows can be rearranged via a draggable handle in the rows headers.
Filtering
- Filter icon appears on hover in the column header.
- Filtering options can also surface in the 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.
- Pinning freezes that column in place — useful when there are enough columns to require horizontal scrolling and understanding the data would benefit from a locked column. Only one column can be pinned at a time.
Bulk action
- Use checkboxes for multi-row selection.
- Selecting a row 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 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.
Responsiveness
Consider limitations of smaller screen sizes when it comes to tables. There are varying levels of refinement to make the table more user-friendly on smaller devices, but it may be worth redesigning the experience altogether, depending on how frequent users are expected to interact with a table on a small screen or touch device.
General best practices
- Prioritize important content: User progressive disclosure to hide less crucial columns or move them to expandable sections.
- Enable horizontal scrolling: Allow users to swipe to view more columns.
- Expandable rows: Hide extra details behind a tap-to-expand interaction.
- Ensure touch-friendly targets: Table rows, Buttons, Checkboxes, and dropdowns should be large enough to tap easily.
- Avoid fixed widths: Use fluid layouts so tables adapt to different screen sizes.
- Alternative designs: Consider converting each row into a Card-like layout on smaller screens.
Touch-friendly interactions
- Tap-friendly row selections: Use checkboxes or larger touch areas.
- Avoid hover-dependent actions: Provide explicit buttons for actions.
- Sticky headers & columns: Keep important labels visible when scrolling.
- Swipe gestures (optional): Enable row actions (e.g., swipe left to delete).
Often used with
Toolbar Pagination, Checkbox selection, Action toolbar for bulk ops, row Menu, Badge / Avatar in cells, Tooltip on truncated values. Last modified on September 16, 2026
