Skip to main content

Table

Rows and columns of comparable records, with headers.

In Dense data

See it live​

Start Storybook to see it live: npm run storybook
Live from StorybookOpen Table in StorybookSee it in dark

When to use it​

In Dense data: The heart of the product: rows of records.

  • Use it when: Records people scan, sort or compare cell by cell.
  • Not when: A grid of teasers (cards), or the shape of a relationship (chart).

Instead:

  • Data table: Many records with search, filters and paging.
  • Chart: The shape of the numbers.

How Dense data uses it​

A number in a table
Use type.data
Not type.body
Mono digits line up in columns, so values compare at a glance.
A selected row or item
Use color.surface.selected
Not color.action.primary as a fill
A light tint shows selection without hiding the data.
Table row height
Use size.row (compact)
Not The comfortable row
Compact rows show more records without scrolling.

Words​

  • Lead with the object, then the state: "Alert 2041 contained."
  • Use numbers, not words for numbers.
  • One verb per button. No "please", no exclamation marks.
  • Use: Investigate, Filter, Assign, Escalated, Resolved. Avoid: Oops, Awesome, Please, Simply.

The labels components use, from the voice tokens:

  • content.action.commit: Save
  • content.action.cancel: Cancel
  • content.action.destroy: Delete
  • content.action.retry: Retry
  • content.action.empty-action: Change filters

See Voice and tone for the whole voice.

Accessibility and keyboard​

Test before you ship:

  • It has a caption and header cells, so each cell is read with its header. undefined

Use it in code​

npx open-ds add table

The component reads only component keys and semantic tokens, so it follows the brand and mode on <html>.

Tokens it reads​

Table reads 14 tokens of its own, each an alias of a semantic token. Each row is one part: its own token, the semantic it aliases, and the value it ends at. Change a semantic and every component that reads it follows; override one of Table's tokens to change Table alone.

Changes with theme

Dense data decides what changes when you switch theme. Here a switch changes colors only, so the marked rows differ between light and dark; everything else holds steady.

PartIts token and the semantic it aliasesValue
Table
Header background
Changes with theme		component.table.header-backgroundcolor.surface.sunkenvar(--table-header-background)Lightslate.light.100:#EEF1F5Darkslate.dark.100:#262D38
Row heightcomponent.table.row-heightsize.rowvar(--table-row-height)size.32:2rem
Cell padding xcomponent.table.cell-padding-xspace.inset.cell-xvar(--table-cell-padding-x)space.12:0.75rem
Row border
Changes with theme		component.table.row-bordercolor.border.defaultvar(--table-row-border)Lightslate.light.200:#DDE2EADarkslate.dark.100:#262D38
Row selected
Changes with theme
when selected		component.table.row-selectedcolor.surface.selectedvar(--table-row-selected)Lightviolet.light.100:#E8ECFFDarkviolet.dark.100:#2A244F
Text sizecomponent.table.font-sizetype.data.font-sizevar(--table-font-size)font.size.13:0.8125rem
Text
Changes with theme		component.table.labelcolor.text.primaryvar(--table-label)Lightslate.light.900:#161B23Darkslate.dark.900:#F7F8FA
Row
Border widthcomponent.table.row.border-widthborder-width.defaultvar(--table-row-border-width)border-width.1:1px
Focus
when selected		component.table.row.focusborder-width.focusvar(--table-row-focus)border-width.2:2px
Head
Text
Changes with theme		component.table.head.labelcolor.text.secondaryvar(--table-head-label)Lightslate.light.700:#3D4655Darkslate.dark.500:#C4CBD6
Font familycomponent.table.head.font-familytype.label.font-familyvar(--table-head-font-family)font.family.ibm-plex-sans:"IBM Plex Sans", system-ui, sans-serif
Text sizecomponent.table.head.font-sizetype.label.font-sizevar(--table-head-font-size)font.size.12:0.75rem
Weightcomponent.table.head.font-weighttype.label.font-weightvar(--table-head-font-weight)font.weight.500:500
Cell
Font familycomponent.table.cell.font-familytype.data.font-familyvar(--table-cell-font-family)font.family.ibm-plex-mono:"IBM Plex Mono", ui-monospace, monospace