Data views

Main DataTable page

There are currently two built-in options for displaying the data DataTable.Table and CardView, but you can also build your own.

DataTable.Table

The Table component is meant to be rendered within a DataTableContext (provided by DataTable here). It displays the data provided by the DataTableContext as an html table.

Table Props API

The DataTable.Table component expects to receive a react-table instance from the DataTableContext.

caption
string | element
Defaultnull
className
string
data
object[] Required
specifies the order and contents of the table's columns and provides display strings for each column's heading. It is composed of an ordered array of objects. Each object contains the following keys:
1. label (string or element; required) contains the display string for each column's heading.
2. key (string; required) maps that label to its corresponding datum for each row in data, to ensure table data are displayed in their appropriate columns.
3. columnSortable (boolean; optional) specifies at the column-level whether the column is sortable. If columnSortable is true, a sort button will be rendered in the column table heading. It is only required if tableSortable is set to true.
4. onSort (function; conditionally required) specifies what function is called when a sortable column is clicked. It is only required if the column's columnSortable is set to true.
5. hideHeader (boolean; optional) specifies at the column-level whether the column label is visible. A column that is sortable cannot have its label be hidden.
6. width (string; conditionally required) only if hasFixedColumnWidths is set to true, the <td> elements' class attributes will be set to this value. This allows restricting columns to specific widths. See Bootstrap's grid documentation for col class names that can be used.
The order of objects in columns specifies the order of the columns in the table.
columns
shape {
key: string Required,
label: string | element Required,
columnSortable: isRequiredIf(PropTypes.bool, props => props.tableSortable),
onSort: isRequiredIf(PropTypes.func, props => props.columnSortable),
hideHeader: bool,
width: isRequiredIf(PropTypes.string, props => props.hasFixedColumnWidths),
}[] Required
specifies the order and contents of the table's columns and provides display strings for each column's heading. It is composed of an ordered array of objects. Each object contains the following keys:
1. label (string or element; required) contains the display string for each column's heading.
2. key (string; required) maps that label to its corresponding datum for each row in data, to ensure table data are displayed in their appropriate columns.
3. columnSortable (boolean; optional) specifies at the column-level whether the column is sortable. If columnSortable is true, a sort button will be rendered in the column table heading. It is only required if tableSortable is set to true.
4. onSort (function; conditionally required) specifies what function is called when a sortable column is clicked. It is only required if the column's columnSortable is set to true.
5. hideHeader (boolean; optional) specifies at the column-level whether the column label is visible. A column that is sortable cannot have its label be hidden.
6. width (string; conditionally required) only if hasFixedColumnWidths is set to true, the <td> elements' class attributes will be set to this value. This allows restricting columns to specific widths. See Bootstrap's grid documentation for col class names that can be used.
The order of objects in columns specifies the order of the columns in the table.
headingClassName
string[]
Specifies Bootstrap class names to apply to the table heading. Options are detailed in Bootstrap's docs.
Default[]
tableSortable
bool
Specifies whether the table is sortable. This setting supercedes column-level sortability, so if it is false, no sortable components will be rendered.
Defaultfalse
hasFixedColumnWidths
bool
Specifies whether the table's columns have fixed widths. Every element in columns must define a width if this is true.
Defaultfalse
defaultSortedColumn
isRequiredIf(PropTypes.string, props => props.tableSortable)
Specifies the key of the column that is sorted by default. It is only required if tableSortable is set to true.
defaultSortDirection
isRequiredIf(PropTypes.string, props => props.tableSortable)
Specifies the direction the defaultSortedColumn is sorted in by default; it will typically be either 'asc' or 'desc'. It is only required if tableSortable is set to true.
sortButtonsScreenReaderText
isRequiredIf( PropTypes.shape({ asc: PropTypes.string, desc: PropTypes.string, defaultText: PropTypes.string, }), props => props.tableSortable, )
Specifies the screen reader only text that accompanies the sort buttons for sortable columns. It takes the form of an object containing the following keys:
1. asc: (string) specifies the screen reader only text for sort buttons in the ascending state.
2. desc: (string) specifies the screen reader only text for sort buttons in the descending state.
3. defaultText: (string) specifies the screen reader only text for sort buttons that are not engaged.
It is only required if tableSortable is set to true.
Default:
```
{
  asc: 'sort ascending',
  desc: 'sort descending',
  defaultText: 'click to sort',
}
```
Default{ asc: 'sort ascending', desc: 'sort descending', defaultText: 'click to sort', }
rowHeaderColumnKey
string
Specifies the key for the column that should act as a row header. Rather than rendering as <td> elements, cells in this column will render as <th scope="row">

Table Subcomponents

Subcomponents of DataTable.Table can be used independently of the main component. They are designed for use with a react-table instance.

TableRow Props API

row
shape {
getRowProps: func Required,
cells: shape {}[] Required,
id: string Required,
isSelected: bool,
isExpanded: bool,
} Required
Row data that is received from react-table API.

TableCell Props API

getCellProps
func Required
Props for the td element
render
func Required
Function that renders the cell contents. Will be called with the string 'Cell'
column
shape {
cellClassName: string,
} Required
Table column

TableHeaderCell Props API

getHeaderProps
func Required
Returns props for the th element
isSorted
bool
Indicates whether or not a column is sorted
Defaultfalse
render
func Required
Renders the header content. Passed the string 'Header'
isSortedDesc
bool
Indicates whether the column is sorted in descending order
Defaultfalse
getSortByToggleProps
func
Gets props related to sorting that will be passed to th
Default() => {}
canSort
bool
Indicates whether a column is sortable
Defaultfalse
headerClassName
string
Class(es) to be applied to header cells
Defaultnull

TableHeaderRow Props API

headerGroups
shape {
headers: shape {
getHeaderProps: func Required,
}[] Required,
getHeaderGroupProps: func Required,
}[] Required

CardView and alternate table components

You may choose to use any table component by using the following code in your display component:

const instance = useContext(DataTableContext)

The CardView takes a CardComponent that is personalized to the table in question and displays a responsive grid of cards.

Sample Card component for use with CardView

The CardComponent prop on CardView represents a table row, and will receive the row that react-table provides as props.

CardView Props API

className
string
The class name for the CardGrid component
Default''
columnSizes
shape {
xs: number,
sm: number,
md: number,
lg: number,
xl: number,
}
An object containing the desired column size at each breakpoint, following a similar props API as react-bootstrap/Col
Default{ xs: 12, lg: 6, xl: 4, }
CardComponent
func Required
Your card component must be individualized to your table. It will be called with props from the "row" of data it will display

const MiyazakiCard = ({ className, original  }) => {
  const { title, director, release_date } = original;

  return (
    <Card className={className}>
      <Card.ImageCap src="https://source.unsplash.com/360x200/?nature,flower" />
      <Card.Section title={title}>
        <dl>
          <dt>Director</dt><dd>{director}</dd>
          <dt>Release Date</dt><dd>{release_date}</dd>
        </dl>
      </Card.Section>
    </Card>
  );
};

Table Props API

caption
string | element
Defaultnull
className
string
data
object[] Required
specifies the order and contents of the table's columns and provides display strings for each column's heading. It is composed of an ordered array of objects. Each object contains the following keys:
1. label (string or element; required) contains the display string for each column's heading.
2. key (string; required) maps that label to its corresponding datum for each row in data, to ensure table data are displayed in their appropriate columns.
3. columnSortable (boolean; optional) specifies at the column-level whether the column is sortable. If columnSortable is true, a sort button will be rendered in the column table heading. It is only required if tableSortable is set to true.
4. onSort (function; conditionally required) specifies what function is called when a sortable column is clicked. It is only required if the column's columnSortable is set to true.
5. hideHeader (boolean; optional) specifies at the column-level whether the column label is visible. A column that is sortable cannot have its label be hidden.
6. width (string; conditionally required) only if hasFixedColumnWidths is set to true, the <td> elements' class attributes will be set to this value. This allows restricting columns to specific widths. See Bootstrap's grid documentation for col class names that can be used.
The order of objects in columns specifies the order of the columns in the table.
columns
shape {
key: string Required,
label: string | element Required,
columnSortable: isRequiredIf(PropTypes.bool, props => props.tableSortable),
onSort: isRequiredIf(PropTypes.func, props => props.columnSortable),
hideHeader: bool,
width: isRequiredIf(PropTypes.string, props => props.hasFixedColumnWidths),
}[] Required
specifies the order and contents of the table's columns and provides display strings for each column's heading. It is composed of an ordered array of objects. Each object contains the following keys:
1. label (string or element; required) contains the display string for each column's heading.
2. key (string; required) maps that label to its corresponding datum for each row in data, to ensure table data are displayed in their appropriate columns.
3. columnSortable (boolean; optional) specifies at the column-level whether the column is sortable. If columnSortable is true, a sort button will be rendered in the column table heading. It is only required if tableSortable is set to true.
4. onSort (function; conditionally required) specifies what function is called when a sortable column is clicked. It is only required if the column's columnSortable is set to true.
5. hideHeader (boolean; optional) specifies at the column-level whether the column label is visible. A column that is sortable cannot have its label be hidden.
6. width (string; conditionally required) only if hasFixedColumnWidths is set to true, the <td> elements' class attributes will be set to this value. This allows restricting columns to specific widths. See Bootstrap's grid documentation for col class names that can be used.
The order of objects in columns specifies the order of the columns in the table.
headingClassName
string[]
Specifies Bootstrap class names to apply to the table heading. Options are detailed in Bootstrap's docs.
Default[]
tableSortable
bool
Specifies whether the table is sortable. This setting supercedes column-level sortability, so if it is false, no sortable components will be rendered.
Defaultfalse
hasFixedColumnWidths
bool
Specifies whether the table's columns have fixed widths. Every element in columns must define a width if this is true.
Defaultfalse
defaultSortedColumn
isRequiredIf(PropTypes.string, props => props.tableSortable)
Specifies the key of the column that is sorted by default. It is only required if tableSortable is set to true.
defaultSortDirection
isRequiredIf(PropTypes.string, props => props.tableSortable)
Specifies the direction the defaultSortedColumn is sorted in by default; it will typically be either 'asc' or 'desc'. It is only required if tableSortable is set to true.
sortButtonsScreenReaderText
isRequiredIf( PropTypes.shape({ asc: PropTypes.string, desc: PropTypes.string, defaultText: PropTypes.string, }), props => props.tableSortable, )
Specifies the screen reader only text that accompanies the sort buttons for sortable columns. It takes the form of an object containing the following keys:
1. asc: (string) specifies the screen reader only text for sort buttons in the ascending state.
2. desc: (string) specifies the screen reader only text for sort buttons in the descending state.
3. defaultText: (string) specifies the screen reader only text for sort buttons that are not engaged.
It is only required if tableSortable is set to true.
Default:
```
{
  asc: 'sort ascending',
  desc: 'sort descending',
  defaultText: 'click to sort',
}
```
Default{ asc: 'sort ascending', desc: 'sort descending', defaultText: 'click to sort', }
rowHeaderColumnKey
string
Specifies the key for the column that should act as a row header. Rather than rendering as <td> elements, cells in this column will render as <th scope="row">

TableCell Props API

getCellProps
func Required
Props for the td element
render
func Required
Function that renders the cell contents. Will be called with the string 'Cell'
column
shape {
cellClassName: string,
} Required
Table column

TableHeaderCell Props API

getHeaderProps
func Required
Returns props for the th element
isSorted
bool
Indicates whether or not a column is sorted
Defaultfalse
render
func Required
Renders the header content. Passed the string 'Header'
isSortedDesc
bool
Indicates whether the column is sorted in descending order
Defaultfalse
getSortByToggleProps
func
Gets props related to sorting that will be passed to th
Default() => {}
canSort
bool
Indicates whether a column is sortable
Defaultfalse
headerClassName
string
Class(es) to be applied to header cells
Defaultnull

TableHeaderRow Props API

headerGroups
shape {
headers: shape {
getHeaderProps: func Required,
}[] Required,
getHeaderGroupProps: func Required,
}[] Required

TableRow Props API

row
shape {
getRowProps: func Required,
cells: shape {}[] Required,
id: string Required,
isSelected: bool,
isExpanded: bool,
} Required
Row data that is received from react-table API.

CardView Props API

className
string
The class name for the CardGrid component
Default''
columnSizes
shape {
xs: number,
sm: number,
md: number,
lg: number,
xl: number,
}
An object containing the desired column size at each breakpoint, following a similar props API as react-bootstrap/Col
Default{ xs: 12, lg: 6, xl: 4, }
CardComponent
func Required
Your card component must be individualized to your table. It will be called with props from the "row" of data it will display

Data views

DataTable.Table

caption

className

data

columns

headingClassName

tableSortable

hasFixedColumnWidths

defaultSortedColumn

defaultSortDirection

sortButtonsScreenReaderText

rowHeaderColumnKey

Table Subcomponents

row

getCellProps

render

column

getHeaderProps

isSorted

render

isSortedDesc

getSortByToggleProps

canSort

headerClassName

headerGroups

CardView and alternate table components

Sample Card component for use with CardView

className

columnSizes

CardComponent

caption

className

data

columns

headingClassName

tableSortable

hasFixedColumnWidths

defaultSortedColumn

defaultSortDirection

sortButtonsScreenReaderText

rowHeaderColumnKey

getCellProps

render

column

getHeaderProps

isSorted

render

isSortedDesc

getSortByToggleProps

canSort

headerClassName

headerGroups

row

className

columnSizes

CardComponent

Guides

Foundations

Components

Buttonlike

Choreography

Content

Forms

Forms (deprecated)

Hooks

Imagery & Iconography

Layout

Navigation

Overlays

Status & metadata

Table

All components (A-Z)