Skip to content
Primer Design System

Primer Design System

Data table

Data table is a 2-dimensional data structure where each row is an item, and each column is a data point about the item.

On this page

  • @primer/react@37.6.0
  • Alpha
  • Reviewed for accessibility

On this page

Import

import {DataTable} from '@primer/react/experimental'

Examples

View in Storybook

Props

DataTable

NameDefaultDescription
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

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

initialSortColumn
string | number

Provide the id or field of the column by which the table is sorted. When using this prop, the input data must be sorted by this column in ascending order

initialSortDirection
'ASC' | 'DESC'

Provide the sort direction that the table should be sorted by on the currently sorted column

Table

NameDefaultDescription
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

NameDefaultDescription
children
React.ReactNode

Table.Actions

NameDefaultDescription
children
React.ReactNode

Table.Body

NameDefaultDescription
children
React.ReactNode

Table.Row

NameDefaultDescription
children
React.ReactNode

Table.Header

NameDefaultDescription
align
'end' | 'start'

The horizontal alignment of the cell's content

children
React.ReactNode

Table.Cell

NameDefaultDescription
align
'end' | 'start'

The horizontal alignment of the cell's content

children
React.ReactNode
scope
'row'

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

Table.CellPlaceholder

No props

Table.Container

NameDefaultDescription
children
React.ReactNode

Table.Divider

No props

Table.Title

NameDefaultDescription
children
React.ReactNode
idRequired
string

Provide a unique id for the table subtitle. This should be used along with aria-labelledby on DataTable

Table.Subtitle

NameDefaultDescription
children
React.ReactNode
idRequired
string

Provide a unique id for the table subtitle. This should be used along with aria-describedby on DataTable

Table.Skeleton

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

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

columnsRequired
Array<Column<Data>>
rows
10number

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

Table.Pagination

NameDefaultDescription
aria-labelRequired
string

Defines a string value that labels the current element. Provide a label for the navigation landmark rendered by this component @see aria-labelledby.

defaultPageIndex
string

Provide an optional index to specify the default selected page

id
string

Optionally provide an id that is placed on the navigation landmark rendered by this component

onChange
({ pageIndex }: { pageIndex: number }) => void

Optionally provide a handler that is called whenever the pagination state is updated

pageSize
25number

Optionally specify the number of items within a page

totalCountRequired
number

Specify the total number of items within the collection

showPages
{narrow: false}boolean | { narrow?: boolean; regular?: boolean; wide?: boolean; }

Whether to show the page numbers

Table.ErrorDialog

NameDefaultDescription
childrenRequired
React.ReactNode

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

title
'Error'string

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.

Table.SortHeader

NameDefaultDescription
directionRequired
'ASC' | 'DESC' | 'NONE'

Specify the sort direction for the TableHeader

onToggleSortRequired
() => void

Provide a handler that is called when the sortable TableHeader is interacted with via a click or keyboard interaction

align
'end' | 'start'

The horizontal alignment of the cell's content

Column options

NameDefaultDescription
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

headerRequired
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''grow' | 'growCollapse' | 'auto' | React.CSSProperties['width']

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