On this page

Data Table

Display structured data in rows and columns for comparison and review.

Overview
Rules and guidance
Properties
Styles
Accessibility

When to use

To display structured data where rows and columns have a meaningful relationship
When users need to compare values across multiple items of the same type
When the data has a consistent structure, with the same attributes for every row

When not to use

For layouts - use Stack or Cluster instead. Tables impose structure that assistive technologies use for navigation, and misusing them creates an inaccessible experience.
For key-value pairs describing a single entity - use Summary List instead, for example a customer's name, address, and account number.
For a single list of values - use a List instead.
For data without a clear row-column relationship - if cells do not gain meaning from their position in both a row and a column, the data is not tabular.

Anatomy

Caption
Column header
Row header
Cell

Basic usage

The simplest way to use DataTable is with the items and columnHeadings props.

Edit live code

<DataTable
  columnHeadings={['Day', 'Average', 'Max', 'Min']}
  items={[
    ['Today', '222', '260', '147'],
    ['Tomorrow', '254', '279', '211'],
    ['Wednesday', '174', '223', '135']
  ]}
  caption={<Strong>National Grid Carbon Intensity Forecast (gCO2/kWh)</Strong>}
/>

Variants and features

Row headers

Use rowHeadings when the first column identifies the row rather than containing a data value, for example a meter serial number or account ID. This renders the first cell of each row as a <th scope="row"> so that screen readers can announce the row identity before each cell value.

Edit live code

<DataTable
  columnHeadings={['Day', 'Average', 'Max', 'Min']}
  items={[
    ['Today', '222', '260', '147'],
    ['Tomorrow', '254', '279', '211'],
    ['Wednesday', '174', '223', '135'],
  ]}
  caption={<Strong>National Grid Carbon Intensity Forecast (gCO2/kWh)</Strong>}
  rowHeadings={true}
/>

Striped rows

Row striping alternates the background colour of odd rows and is on by default. It helps users track across wide tables. Only disable striping for compact tables where alternating backgrounds add visual noise without helping readability.

Striping on, the default:

Edit live code

<DataTable
  columnHeadings={['Day', 'Average', 'Max', 'Min']}
  items={[
    ['Today', '222', '260', '147'],
    ['Tomorrow', '254', '279', '211'],
    ['Wednesday', '174', '223', '135'],
  ]}
  caption={<Strong>Striped (default)</Strong>}
  rowHeadings={true}
/>

Striping off, with striped={false}:

Edit live code

<DataTable
  columnHeadings={['Day', 'Average', 'Max', 'Min']}
  items={[
    ['Today', '222', '260', '147'],
    ['Tomorrow', '254', '279', '211'],
    ['Wednesday', '174', '223', '135'],
  ]}
  caption={<Strong>Not striped</Strong>}
  rowHeadings={true}
  striped={false}
/>

Fixed column widths

Use columnWidths to prevent columns from resizing as content changes. Pass a CSS width value for each column position. Columns without a fixed width will share the remaining space.

Edit live code

<DataTable
  columnHeadings={['Day', 'Average', 'Max', 'Min']}
  items={[
    ['Today', '222', '260', '147'],
    ['Tomorrow', '254', '279', '211'],
    ['Wednesday', '174', '223', '135'],
  ]}
  caption={<Strong>National Grid Carbon Intensity Forecast (gCO2/kWh)</Strong>}
  rowHeadings={true}
  columnWidths={['12rem', '6rem', '6rem', '6rem']}
/>

Composable usage

For tables that need custom rendering, for example mixed cell types or specific row grouping that the items prop cannot express, use the exported sub-components directly as children.

The sub-components are: TableHead, TableBody, TableRow, TableHeader, TableRowHeader, TableCell, and TableCaption. Each accepts a cellWidth prop in addition to its native HTML element attributes.

When composing, the striped prop does not apply. Set stripe on each alternating TableRow yourself.

Edit live code

<DataTable>
  <TableCaption>
    <Strong>Meter reads awaiting validation</Strong>
  </TableCaption>
  <TableHead>
    <TableRow>
      <TableHeader scope="col">Meter serial</TableHeader>
      <TableHeader scope="col">Reading</TableHeader>
      <TableHeader scope="col">Status</TableHeader>
    </TableRow>
  </TableHead>
  <TableBody>
    <TableRow>
      <TableRowHeader scope="row">A1234567</TableRowHeader>
      <TableCell>12,044</TableCell>
      <TableCell><Badge variant="success">Accepted</Badge></TableCell>
    </TableRow>
    <TableRow stripe>
      <TableRowHeader scope="row">B7654321</TableRowHeader>
      <TableCell>8,910</TableCell>
      <TableCell><Badge variant="warning">Pending</Badge></TableCell>
    </TableRow>
  </TableBody>
</DataTable>

DataTable

Also accepts all props from HTMLAttributes, TableHTMLAttributes.

Name	Type	Default	Required	Description
items	ReactNode[][]	—	No	Table body content as an array of rows, each an array of cell contents.
columnHeadings	ReactNode[]	—	No	Content of the column header cells, rendered in a header row above the body.
caption	ReactNode	—	No	Visible caption for the table, which also labels the scrollable container for assistive technology.
rowHeadings	boolean	—	No	Renders the first cell of each row as a row header (`th scope="row"`) rather than a data cell.
columnWidths	string[]	—	No	CSS widths for each column, matched to cells by index, for example `['20%', '10rem']`.
striped	boolean	true	No	Gives alternate body rows a muted background.

TableCaption

Also accepts all props from HTMLAttributes.

Name	Type	Default	Required	Description
as	ElementType	—	No	Renders the component as a different element or component, e.g. `as="section"`.
forwardedAs	ElementType	—	No	Like `as`, but passed on to the component being wrapped, for when a styled wrapper should keep its own element and change the one beneath it.

TableHead

Also accepts all props from HTMLAttributes.

Name	Type	Default	Required	Description
as	ElementType	—	No	Renders the component as a different element or component, e.g. `as="section"`.
forwardedAs	ElementType	—	No	Like `as`, but passed on to the component being wrapped, for when a styled wrapper should keep its own element and change the one beneath it.

TableHeader

Also accepts all props from HTMLAttributes, ThHTMLAttributes.

Name	Type	Default	Required	Description
cellWidth	string	—	No	CSS width of the cell's column, for example `20%` or `10rem`.
as	ElementType	—	No	Renders the component as a different element or component, e.g. `as="section"`.
forwardedAs	ElementType	—	No	Like `as`, but passed on to the component being wrapped, for when a styled wrapper should keep its own element and change the one beneath it.

TableBody

Also accepts all props from HTMLAttributes.

Name	Type	Default	Required	Description
as	ElementType	—	No	Renders the component as a different element or component, e.g. `as="section"`.
forwardedAs	ElementType	—	No	Like `as`, but passed on to the component being wrapped, for when a styled wrapper should keep its own element and change the one beneath it.

TableRow

Also accepts all props from HTMLAttributes.

Name	Type	Default	Required	Description
stripe	boolean	—	No	Gives the row a muted background, as used for alternate rows.
as	ElementType	—	No	Renders the component as a different element or component, e.g. `as="section"`.
forwardedAs	ElementType	—	No	Like `as`, but passed on to the component being wrapped, for when a styled wrapper should keep its own element and change the one beneath it.

TableCell

Also accepts all props from HTMLAttributes, TdHTMLAttributes.

Name	Type	Default	Required	Description
cellWidth	string	—	No	CSS width of the cell's column, for example `20%` or `10rem`.
as	ElementType	—	No	Renders the component as a different element or component, e.g. `as="section"`.
forwardedAs	ElementType	—	No	Like `as`, but passed on to the component being wrapped, for when a styled wrapper should keep its own element and change the one beneath it.

TableRowHeader

Also accepts all props from HTMLAttributes, ThHTMLAttributes.

Name	Type	Default	Required	Description
cellWidth	string	—	No	CSS width of the cell's column, for example `20%` or `10rem`.
as	ElementType	—	No	Renders the component as a different element or component, e.g. `as="section"`.
forwardedAs	ElementType	—	No	Like `as`, but passed on to the component being wrapped, for when a styled wrapper should keep its own element and change the one beneath it.

Styles

table-container

overflow-x: auto;
white-space: nowrap;

:focus-visible {
  ${focusRing}
}

table

border-radius: ${radii.standard};
border-collapse: separate;
width: 100%;
table-layout: auto;
white-space: nowrap;

table-header

padding: ${space[2]};
font-weight: ${fontWeights.bold};
text-align: left;
color: ${colors.heading};
background-color: ${colors.canvas};
border-bottom: ${borderWidths.standard} solid ${colors.border};

&[cellWidth] {
  width: ${cellWidth};
}
font-family: ${fonts.body};
font-size: ${responsiveFontSizes.body[0]};

${mediaQueries.smallAndUp} {
  font-size: ${responsiveFontSizes.body[1]};
}

table-row-header

padding: ${space[2]};
border-bottom: ${borderWidths.standard} solid ${colors.borderMuted};
font-weight: ${fontWeights.bold};
text-align: left;
color: ${colors.heading};

&[cellWidth] {
  width: ${cellWidth};
}
font-family: ${fonts.body};
font-size: ${responsiveFontSizes.body[0]};

${mediaQueries.smallAndUp} {
  font-size: ${responsiveFontSizes.body[1]};
}

table-caption

font-weight: ${fontWeights.bold};
text-align: left;
color: ${colors.heading};
padding: ${space[2]};

table-row

background-color: ${stripe ? colors.canvasMuted : colors.canvas};

table-cell

font-weight: ${fontWeights.normal};
font-family: ${fonts.body};
font-size: ${responsiveFontSizes.body[0]};
padding: ${space[2]};
border-bottom: ${borderWidths.standard} solid ${colors.borderMuted};
color: ${colors.body};

&[cellWidth] {
  width: ${cellWidth};
}

${mediaQueries.smallAndUp} {
  font-size: ${responsiveFontSizes.body[1]};
}

In brief

Data Table is a native table. A screen reader announces the caption, the column headings and, with rowHeadings, the row headings as it moves through the cells. A wide table sits in a scroll region.

What Nebula provides

It renders a native table, so the browser associates each cell with its headers. The columnHeadings and rowHeadings props set scope on the header cells.
The caption prop labels the table and its scroll region.
A table wider than its container becomes a tab stop, with a visible focus ring, so a keyboard user can scroll it.

Keyboard behaviour

The table is not a tab stop unless it is wider than its container. Then the scroll region is, reached with Tab.

Interactions

Tab - Moves focus to the scroll region when the table is wider than its container

Accessible design

Use a table only for data in rows and columns

A screen reader announces every cell with its headings, so a table used for layout reads as nonsense.

WCAG: 1.3.1 Info and Relationships

Give every table a caption that says what it shows

The caption is the table's name. Without it a screen reader user reaches the table with no idea what it holds.

WCAG: 2.4.6 Headings and Labels

Write column headings that make sense on their own

A screen reader announces the heading with every cell, so "Max" is clearer than "Value" next to "Tomorrow".

WCAG: 2.4.6 Headings and Labels 1.3.1 Info and Relationships

Accessible development

Pass the caption with the caption prop

The prop names the table and the scroll region around it. A TableCaption passed as a child names the table but not the scroll region, which is then announced as a group with no name.

WCAG: 1.3.1 Info and Relationships

If you build the table from children, set scope on every header cell

Only the columnHeadings and rowHeadings props set scope. A TableHeader or TableRowHeader passed as a child has none, so set scope="col" or scope="row" yourself.

WCAG: 1.3.1 Info and Relationships

Accessibility testing status

Reviewed on 9 October 2026 against v17.0.1.

Test	Status	Tested with
Default state	Tested	axe-core via the Storybook test runner (CI)
Advanced states	Partially tested	axe-core via the Storybook test runner (CI)
Keyboard navigation	Partially tested	keyboard (reported by the owner)
Screen reader	Partially tested	VoiceOver with Chrome (reported by the owner)

What these tests and statuses mean

The table records which checks were run on this component on its own. It is not a statement of WCAG conformance, and it does not cover how the component is used.

The tests

Default state: The component as it first appears, before anything is clicked or changed.
Advanced states: Every other state and variant: error, open, selected, each size and style, and hovering.
Keyboard navigation: Whether every function can be reached and used with the keyboard alone, with a visible focus ring.
Screen reader: Whether a screen reader announces what is on screen correctly: the name, the role and any state.

The statuses

Tested: Every check in this row passed in an automated run that repeats on every pull request.
Manually tested: Every check in this row was run once, by a person or with a tool they started, and all of them passed. It is not re-run on every change.
Partially tested: Some checks in this row were run once and passed; the rest are still to do.
Issue found: A check in this row failed. The ticket is shown beside the status.
Not tested: No check in this row has been run yet.
Not applicable: This row does not apply to the component, for the reason given beside it.

When to use​

When not to use​

Anatomy​

Basic usage​

Variants and features​

Row headers​

Striped rows​

Fixed column widths​

Composable usage​

usage​

content​

interaction​

composition​

DataTable​

TableCaption​

TableHead​

TableHeader​

TableBody​

TableRow​

TableCell​

TableRowHeader​

Styles​

table-container​

table​

table-header​

table-row-header​

table-caption​

table-row​

table-cell​

In brief​

What Nebula provides​

Keyboard behaviour​

Interactions​

Accessible design​

Use a table only for data in rows and columns​

Give every table a caption that says what it shows​

Write column headings that make sense on their own​

Accessible development​

Pass the caption with the caption prop​

If you build the table from children, set scope on every header cell​

Accessibility testing status​

When to use

When not to use

Anatomy

Basic usage

Variants and features

Row headers

Striped rows

Fixed column widths

Composable usage

usage

content

interaction

composition

DataTable

TableCaption

TableHead

TableHeader

TableBody

TableRow

TableCell

TableRowHeader

Styles

table-container

table

table-header

table-row-header

table-caption

table-row

table-cell

In brief

What Nebula provides

Keyboard behaviour

Interactions

Accessible design

Use a table only for data in rows and columns

Give every table a caption that says what it shows

Write column headings that make sense on their own

Accessible development

Pass the caption with the caption prop

If you build the table from children, set scope on every header cell

Accessibility testing status