Compare structured data
Use tables when each record shares the same fields.
Components
Handle dense records
Rows and columns give repeated information a predictable position.
Support row actions
Include links or controls, with behaviour handled by your application.
1
Header row
2
Data row
3
Data cell
4
Border (optional)
5
Header cell
6
Header background (optional)
7
Row divider (bottom)
Header position
Use headerPosition with rowHeader, columnHeader and tableData to generate headers across the top, down the side, or both. When using slotted rows, arrange the headers manually.
Headers across the top. Most common arrangement for tabular data.
Header background
Use headerBackground to apply a tinted fill to the header cells for stronger visual separation from the body.
Plain header. Suits tables embedded in low-contrast surfaces.
Table border
Use tableBorder to add an outer border to a table with slotted rows. Horizontal row dividers remain visible with or without this option.
Horizontal dividers separate rows without an outer border.
Horizontal scrolling
Keep wide tables in a labelled, keyboard-focusable container that scrolls horizontally. Rows and columns keep their structure. The legacy responsive property is deprecated.
Focus the container and use the Left and Right arrow keys to scroll when the table is wider than the available space.
Table layout
Table layout controls whether columns size automatically or use fixed distribution.
Use auto layout when content length should 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-md16pxsgds-padding-sm—sgds-border-width-0Width variessgds-border-width-11pxsgds-font-weight-semibold—sgds-dimension-56—When to use
- Use a table to present static or already-prepared information in rows and columns, so users can easily scan and compare values.
- Use it when you only need to display tabular information. A table does not manage behaviours such as sorting, pagination, row selection, loading states or expandable rows.
- You can still use a table if you need custom interactions, but these behaviours need to be handled separately by your application.
When not to use
- Do not use a table when users need built-in features to navigate or manage a dataset, such as sorting, pagination, row selection or expandable rows. Use a data table instead.
- Do not use a table for information that is better presented as a list, card or description list.
Keep related values in consistent columns
Put the same type of information in each column so users can compare records.
Do not force item details into a table
Consider a description list when presenting one item’s details, such as its name, email, and role.
Use descriptive column headers
Choose headers that explain the values below them, such as “Service”, “Owner”, and “Status”.
Do not crowd rows with actions
Keep primary actions visible. Group secondary actions in an overflow menu when space is limited.
Built-in accessibility
- The component provides table, row, header and cell semantics for structured data.
- The table wrapper is focusable, including when the legacy responsive property is not set. It does not provide spreadsheet-style cell navigation.
Labels and content
- Use clear headers. For row headers, use the data-generated table with
headerPositionrather than assuming a slotted header becomes a row header when moved to the left. Slottedsgds-table-headelements use the columnheader role. - Keep cell content concise and avoid using tables for page layout.
- Give repeated action links or buttons labels that identify the record, such as “View application APP-0421”.
Focus and interaction
- Keep interactive elements in the same order as the table content. Ordinary data cells do not need to be in the Tab sequence.
- Preserve headers when adapting tables to smaller screens. Give any horizontal scroll region an accessible name, keyboard focus and a visible focus indicator.
TabShift+TabLeftorRight arrowEnterorSpaceHave suggestions or feedback?
Share them with us on Slack → #ask-sgds-v3
Found a bug or issue?
Report it on GitHub Issues → sgds-web-component