Compare records
Use data tables when each row shares the same set of fields.
Components
Data table
A data table is designed for managing and displaying large datasets with interactive features that enhance usability and accessibility. It allows users to analyse, sort, and manipulate data efficiently.
Navigate long datasets
Built-in pagination helps users move through many records.
Act on rows
Support sorting, selection, and expandable details where needed.
Submitted by Operations on 12 Mar 2026.
1
Header row
2
Data row
3
Expanded panel
4
Footer (optional)
5
Expand indicator
6
Checkbox
7
Header cell
8
Sorting (optional)
Header props
Configure header cells with supported sgds-data-table-head props.
Set sorting and sortKey on headers that should sort rows.
Row expansion
Use supported sgds-data-table-row props for expandable row details.
More details about John Doe.
Set expand on rows that reveal detail content.
Row selection
Use multiSelect on the table and checked on rows for selection states.
Set multiSelect to render a checkbox column for row selection.
Pagination
Configure result count, items per page, summary text, and pagination variant.
Use currentPage, dataLength, and itemsPerPage for default pagination.
Mode and server sort
Choose client or server pagination, and use serverSort when an API handles sorting.
Default. Client mode slices slotted rows and handles local sorting.
Data state
Use the built-in loading and no-data states shown in Storybook.
With no body rows, the table shows the default no-data state.
Table layout
Choose how the browser sizes columns inside the data table.
Default. Use layout="auto" to let content influence column sizing.
Design tokens used
Each row is a colour, spacing, or size value the component uses, and the right-most column tells you where in the component you'll see it.
sgds-padding-sm—sgds-padding-md16pxsgds-padding-lg20pxsgds-padding-2-xl32pxsgds-padding-4-xl—sgds-gap-2-xs4pxsgds-border-width-11pxsgds-border-radius-none—sgds-form-border-radius-sm—sgds-font-family-brand—sgds-font-size-label-sm—sgds-font-weight-semibold—sgds-font-weight-regular—sgds-line-height-2-xsHeight variessgds-letter-spacing-normal—sgds-outline-focus—sgds-outline-offset-focus—When to use
- Use a data table to display and manage structured datasets, where each row represents a record and each column represents a shared field.
- Use it when users need built-in features to work with the dataset, such as sorting, pagination, row selection or expandable rows.
- Use it when the data changes or is loaded over time and you need to represent states and behaviours such as loading, no data, or server-side sorting and pagination.
When not to use
- Do not use a data table when you only need to present already-prepared information in rows and columns without built-in data management features. Use a table instead.
- Do not use a data table for information that is better presented as a list, card or description list.
Use data tables for interactive datasets
Use a data table when records need built-in behaviours such as sorting, pagination, selection, loading states, or expandable row details.
Do not use data tables for static tables
If the content is already prepared and does not need built-in data management features, use a table instead.
Use clear headers and stable sort keys
Set sorting and sortKey only on columns users can compare. This gives client sorting and server sort events a stable field name.
Do not make action columns sortable
Keep sorting to data columns. Action and control columns should not emit sort events.
Use loading and no-data states
Set loading while rows are being fetched, and use the no-data slot when the current query returns no records.
Do not use a data table for one record
For attributes of a single item, a description list shows the label-value relationship more clearly.
Built-in accessibility
Data table renders table semantics from composed SGDS row, header, and cell elements.
- Header cells are rendered with column scope and body cells are rendered as table cells.
- Sortable headers expose
aria-sortand can be focused when sorting is enabled. - The no-data state uses a status region so updates can be announced.
- Row selection uses SGDS checkboxes, including the header checkbox for select-all behaviour.
- Expandable rows render a focusable control cell and fire show and hide lifecycle events.
Labels and content
Clear column headers and concise row content help users understand the relationship between cells.
- Use short, unique column headers that describe the data in that column.
- Set
sortKeyon sortable headers so selected-row and sort events use stable keys. - Use the
no-dataslot to explain empty results and give users a next step. - Avoid putting large paragraphs inside table cells. Use expandable row content for supporting details.
TabEnterSpaceHave suggestions or feedback?
Share them with us on Slack → #ask-sgds-v3
Found a bug or issue?
Report it on GitHub Issues → sgds/components/data-table