Skip to content
Primer Design System/React

Primer Design System

Site navigation

On this page

DataTable

  • Draft
  • Reviewed for accessibility
On this page

Props

DataTable

NameTypeDefaultDescription
aria-describedby
string

Provide an id to an element which uniquely describes this table

aria-labelledby
string

Provide an id to an element which uniquely labels this table

data
Array<Data>

Provide a collection of the rows which will be rendered inside of the table

columns
Array<Column<Data>>

Provide the columns for the table and the fields in data to which they correspond

cellPadding
'condensed' | 'normal' | 'spacious'

Specify the amount of space that should be available around the contents of a cell

Table

NameTypeDefaultDescription
aria-describedby
string

Provide an id to an element which uniquely describes this table

aria-labelledby
string

Provide an id to an element which uniquely labels this table

children
React.ReactNode
cellPadding
'condensed' | 'normal' | 'spacious'

Specify the amount of space that should be available around the contents of a cell

Table.Head

NameTypeDefaultDescription
children
React.ReactNode

Table.Body

NameTypeDefaultDescription
children
React.ReactNode

Table.Row

NameTypeDefaultDescription
children
React.ReactNode

Table.Header

NameTypeDefaultDescription
children
React.ReactNode

Table.Cell

NameTypeDefaultDescription
children
React.ReactNode
scope
'row'

Provide the scope for a table cell, useful for defining a row header using scope="row"

Table.Container

NameTypeDefaultDescription
children
React.ReactNode

Table.Title

NameTypeDefaultDescription
children
React.ReactNode
id Required
string

Table.Subtitle

NameTypeDefaultDescription
children
React.ReactNode
id Required
string

Table.Skeleton

NameTypeDefaultDescription
cellPadding
'condensed' | 'normal' | 'spacious'

Specify the amount of space that should be available around the contents of a cell

columns
Array<Column<Data>>
rows
number

Optionally specify the number of rows which should be included in the skeleton state of the component

Table.Pagination

NameTypeDefaultDescription
aria-label Required
string
defaultPageIndex
string
id
string
onChange
({ pageIndex }: { pageIndex: number }) => void
pageSize
number
totalCount Required
number

Table.ErrorDialog

NameTypeDefaultDescription
children Required
React.ReactNode

The content of the dialog. This is usually a message explaining the error.

title
string
'Error'

The title of the dialog. This is usually a short description of the error.

onRetry
() => void

Event handler called when the user clicks the retry button.

onDismiss
() => void

Event handler called when the dialog is dismissed.

Column options

NameTypeDefaultDescription
align
'start' | 'end'

The horizontal alignment of the column's content

field
ObjectPaths<Data>

Optionally provide a field to render for this column. This may be the key of the object or a string that accesses nested objects through .. For example: field: a.b.c Alternatively, you may provide a renderCell for this column to render the field in a row

header Required
string | (() => React.ReactNode)

Provide the name of the column. This will be rendered as a table header within the table itself

maxWidth
React.CSSProperties['maxWidth']

The maximum width the column can grow to

minWidth
React.CSSProperties['minWidth']

The minimum width the column can grow to

renderCell
(data: Data) => React.ReactNode

Provide a custom component or render prop to render the data for this column in a row

rowHeader
boolean

Specify if the value of this column for a row should be treated as a row header

sortBy
boolean | 'alphanumeric' | 'basic' | 'datetime' | (a: Data, b: Data) => number

Specify if the table should sort by this column and, if applicable, a specific sort strategy or custom sort strategy

width
'grow' | 'growCollapse' | 'auto' | React.CSSProperties['width']
'grow'

Controls the width of the column.

  • 'grow': Stretch to fill available space, and min width is the width of the widest cell in the column
  • 'growCollapse': Stretch to fill available space or shrink to fit in the available space. Allows the column to shrink smaller than the cell content's width.
  • 'auto': The column is the width of it’s widest cell. Not intended for use with columns who’s content length varies a lot because a layout shift will occur when the content changes
  • explicit width: Will be exactly that width and will not grow or shrink to fill the parent

Status

Alpha

  • Component props and basic example usage of the component are documented on primer.style/react.
  • Component does not have any unnecessary third-party dependencies.
  • Component can adapt to different themes.
  • Component can adapt to different screen sizes.
  • Component has robust unit test coverage (100% where achievable).
  • Component has visual regression coverage of its default and interactive states.
  • Component does not introduce any axe violations.
  • Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

Beta

  • Component is used in a production application.
  • Common usage examples are documented on primer.style/react.
  • Common usage examples are documented in storybook stories.
  • Component has been reviewed by a systems designer and any resulting issues have been addressed.
  • Component does not introduce any performance regressions.

Stable

  • Component API has been stable with no breaking changes for at least one month.
  • Feedback on API usability has been sought from developers using the component and any resulting issues have been addressed.
  • Component has corresponding design guidelines documented in the interface guidelines.
  • Component has corresponding Figma component in the Primer Web library.
  • Tooling (such as linters, codemods, etc.) exists to prevent further use of alternatives.