Paragon Design System

Technical Documentation

npm_version
Changelog
GitHub

DataTable

The DataTable component is a wrapper that uses the react-table library to create tables. It can be used as is, or its subcomponents can be used on their own, allowing the developer full control.

Paragon also exports all React hooks from react-table allowing the developers to use them and make customizations more freely without adding react-table as a separate dependency to their project. For full list of available hooks view react-table API reference.

How children get information

The table context gets the current react-table instance of the table from the DataTable component and makes it available to any child component within the DataTable provider. In addition to the react-table instance, itemCount, numBreakoutFilters, and bulkActions, and any props that are not listed in the props table below are available to child components through the DataTableContext.

How to use context in a custom component:

const instance = useContext(DataTableContext)

Frontend filtering and sorting

For small tables (less than ~10,000 rows), filtering, sorting and pagination can be done quickly and easily on the frontend.

In this example, a default TextFilter component is used for all columns. A default filter can be passed in, or a filter component can be defined on the column. See react-table filters documentation for more information.

Backend filtering and sorting

For larger tables, it may make sense to do filtering, pagination and sorting on the backend. The user must pass a fetchData function, which will be called when the filtering, sorting, or pagination data changes. The manualFilters, manualPagination, and manualSortBy props may also be needed.

When fetchData is called, it is given the necessary data to send a backend API request using the appropriate filters, page number, and/or ordering parameter. Once the request resolves, be sure to update the data prop to reflect the updated data.

Paginated selection

To enable proper selection behavior with backend pagination (i.e., when isSelectable is provided), for both individual rows and bulk actions, the controlled selection status and controlled select components must be used. When used, these components keep track of a user's row selections in a React context provider such that they persist during pagination, even when only 1 page of data is known at any given time. The following components must be used, as shown in the below example:

  • DataTable.ControlledSelectionStatus
  • DataTable.ControlledSelectHeader
  • DataTable.ControlledSelect
NOTE: While the below example doesn't demonstrate using true backend filtering, pagination, and sorting, it does mock the behavior of making an asynchronous API request and updating the table data.

View Switching

Card view is default when isDataViewToggleEnabled is true.

See dataViewToggleOptions props documentation for all supported props.

NOTE: you have to memoize data to persist filters choices during view switch, see code example below.

With a default active state specified

Loading state

Can be used to show the loading state when DataTable is asynchronously fetching new data.

Actions, Table actions and Bulk actions

Actions and bulk actions are actions that are performed on table rows, though bulk actions can be used for actions that apply to the whole table. It is up to the user to determine what the action does.

Table Actions

Table actions are actions that are enacted on the entire table. Their click handler is called with the react-table instance. The first two table actions will be displayed as buttons, while the remaining actions will be displayed in an overflow dropdown menu. Table actions are not visible if bulk actions are available and there are selected rows.

Bulk Actions

Bulk actions are action that are enacted on specific table rows. The bulk action click handler is called with the selected rows. The first two bulk actions will be displayed as buttons, while the remaining bulk actions will be displayed in a overflow dropdown menu. Bulk actions are not visible unless rows have been selected.

Actions

An action can also be defined as an additional column on the table. The Cell property can be defined to display any component that a user requires. It will receive the row as props. You can pass a function to render custom components for bulk actions and table actions.

Actions with Data view toggle enabled

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.

Customizing number of Cards shown per row

Use columnSizes prop of CardView component to define how many Cards are shown per row at each breakpoint.

columnSizes is an object containing the desired column size at each breakpoint. The example below shows 1 Card per row at xs breakpoint, 2 Cards at sm and md, and 4 Cards at lg and higher. You can read more about the API at https://react-bootstrap.netlify.app/layout/grid/.

Horizontal view

You can also display Cards with horizontal view. If the table is selectable control position of selection checkbox with selectionPlacement prop, accepts right or left positions (relative to the Card).

Sidebar Filter

For a more desktop friendly view, you can move filters into a sidebar by providing showFiltersInSidebar prop, try it out!

Expandable rows

DataTable supports expandable rows which once expanded render additional content under the row. Displayed content is controlled by the renderRowSubComponent prop, which is a function that receives row as its single prop and renders expanded view, you also need to pass isEpandable prop to DataTable to indicate that it should support expand behavior for rows. Finally, an additional column is required to be included into columns prop which will contain handlers for expand / collapse behavior, see examples below.

Default view

Here we use default expander column offered by Paragon and for each row render value of the name attribute as its subcomponent.

With custom expander column

You can create your own custom expander column and use it, see code example below.

Custom cell content

You can create your own cell content by passing the Cell property to a specific column.

DataTable Props API
  • columns shape {
    Header: func | node Required,
    accessor: requiredWhenNot(PropTypes.string, 'Cell'),
    Cell: func | element,
    Filter: func,
    filter: string,
    filterChoices: shape {
    name: string,
    number: number,
    value: string,
    }    []    ,
    }    []     Required

    Definition of table columns

  • data shape {}[] Required

    Data to be displayed in the table

  • isSelectable bool

    table rows can be selected

    Defaultfalse
  • manualSelectColumn shape {
    id: string Required,
    Header: func | node Required,
    Cell: func Required,
    disableSortBy: bool Required,
    }

    Alternate column for selecting rows. See react table useSort docs for more information

  • isSortable bool

    Table columns can be sorted

    Defaultfalse
  • manualSortBy bool

    Indicates that sorting will be done via backend API. A fetchData function must be provided

    Defaultfalse
  • isPaginated bool

    Paginate the table

    Defaultfalse
  • manualPagination bool

    Indicates that pagination will be done manually. A fetchData function must be provided

    Defaultfalse
  • pageCount requiredWhen(PropTypes.number, 'manualPagination')
  • isFilterable bool

    Table rows can be filtered, using a default filter in the default column values, or in the column definition

    Defaultfalse
  • manualFilters bool

    Indicates that filtering will be done via a backend API. A fetchData function must be provided

    Defaultfalse
  • defaultColumnValues shape {
    Filter: func | node,
    }

    defaults that will be set on each column. Will be overridden by individual column values

    Default{}
  • additionalColumns shape {
    id: string Required,
    Header: string | node,
    Cell: func | node,
    }    []

    Actions or other additional non-data columns can be added here

    Default[]
  • fetchData func

    Function that will fetch table data. Called when page size, page index or filters change. Meant to be used with manual filters and pagination

    Defaultnull
  • initialState shape {
    pageSize: requiredWhen(PropTypes.number, 'isPaginated'),
    pageIndex: requiredWhen(PropTypes.number, 'isPaginated'),
    filters: requiredWhen(PropTypes.arrayOf(PropTypes.shape()), 'manualFilters'),
    sortBy: requiredWhen(PropTypes.arrayOf(PropTypes.shape()), 'manualSortBy'),
    selectedRowIds: shape {
    0: any,
    1: any,
    2: any,
    3: any,
    4: any,
    5: any,
    6: any,
    7: any,
    8: any,
    9: any,
    10: any,
    11: any,
    12: any,
    13: any,
    14: any,
    15: any,
    16: any,
    }    ,
    }

    Initial state passed to react-table's documentation https://react-table.tanstack.com/docs/api/useTable

    Default{}
  • initialTableOptions shape {}

    Table options passed to react-table's useTable hook. Will override some options passed in to DataTable, such as: data, columns, defaultColumn, manualFilters, manualPagination, manualSortBy, and initialState

    Default{}
  • itemCount number Required

    Actions to be performed on the table. Called with the table instance. Not displayed if rows are selected.

  • bulkActions shape {
    buttonText: string Required,
    handleClick: func Required,
    className: string,
    variant: string,
    disabled: bool,
    }     | func | element    []     | func | element

    Actions to be performed on selected rows of the table. Called with the selected rows. Only displayed if rows are selected.

    Default[]
  • tableActions shape {
    buttonText: string Required,
    handleClick: func Required,
    className: string,
    variant: string,
    disabled: bool,
    }     | func | element    []     | func | element

    Function for rendering custom components, called with the table instance

    Default[]
  • numBreakoutFilters enum1 | 2 | 3 | 4

    Number between one and four filters that can be shown on the top row.

    Default1
  • EmptyTableComponent func

    Component to be displayed when the table is empty

    DefaultEmptyTableContent
  • RowStatusComponent func

    Component to be displayed for row status, ie, 10 of 20 rows. Displayed by default in the TableControlBar

    DefaultRowStatus
  • SelectionStatusComponent func

    Component to be displayed for selection status. Displayed when there are selected rows and no active filters

    DefaultSelectionStatus
  • FilterStatusComponent func

    Component to be displayed for filter status. Displayed when there are active filters.

    DefaultFilterStatus
  • children node[] | node

    If children are not provided a table with control bar and footer will be rendered

    Defaultnull
  • showFiltersInSidebar bool

    If true filters will be shown on sidebar instead

    Defaultfalse
  • dataViewToggleOptions shape {
    isDataViewToggleEnabled: bool,
    onDataViewToggle: func,
    defaultActiveStateValue: string,
    togglePlacement: string,
    }

    options for data view toggle

    Default{ isDataViewToggleEnabled: false, onDataViewToggle: () => {}, defaultActiveStateValue: 'card', togglePlacement: 'left', }
  • disableElevation bool

    Remove the default box shadow on the component

    Defaultfalse
  • renderRowSubComponent func

    A function that will render contents of expanded row, accepts row as a prop.

  • isExpandable bool

    Indicates whether table supports expandable rows.

    Defaultfalse
  • isLoading bool

    Indicates whether the table should show loading states.

    Defaultfalse
  • onSelectedRowsChanged func

    Callback function called when row selections change.

DataViewToggle Props API
This component does not receive any props.
BulkActions Props API
  • className string

    class names for the div wrapping the button components

    Defaultnull
TableActions Props API
  • className string

    class names for the div wrapping the button components

Table Props API
  • caption string | element
    Defaultnull
  • className string
  • data shape {}[] 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">

CardView Props API
  • className string

    The class name for the CardGrid component

  • 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

  • selectionPlacement enum'left' | 'right'

    If the Cards are selectable this prop determines from which side of the Card to show selection component.

    Default'right'
  • SkeletonCardComponent func

    Overrides default skeleton card component for loading state in CardView

  • skeletonCardCount number

    Customize the number of loading skeleton cards to display in CardView

    Default8
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.

FilterStatus Props API
  • className string
    Defaultnull
  • buttonClassName string
    Default'pgn__smart-status-button'
  • variant string
    Default'link'
  • size string
    Default'inline'
  • clearFiltersText element | string
  • showFilteredFields bool
    Defaulttrue
SelectionStatus Props API
  • className string

    A class name to append to the base element

  • clearSelectionText string | element

    A text that appears on the Clear selection button, defaults to 'Clear Selection'

RowStatus Props API
  • className string

    Specifies class name to append to the base element.

  • statusText string | element

    A text describing how many rows is shown in the table.

SmartStatus Props API
This component does not receive any props.
TablePagination Props API
This component does not receive any props.
TextFilter Props API
  • column shape {
    setFilter: func Required,
    Header: func | node Required,
    getHeaderProps: func Required,
    filterValue: string,
    }     Required

    Specifies a column object.

    setFilter: Function to set the filter value.

    Header: Column header used for labels and placeholders.

    getHeaderProps: Generates a key unique to the column being filtered.

    filterValue: Value for the filter input.

Contents

Guides

Foundations

PlaygroundBeta

  • A drag-and-drop UI builder for prototyping with Paragon components.

Components

Buttonlike

Choreography

Content

Forms

Forms (deprecated)

Hooks

Imagery & Iconography

Layout

Navigation

Overlays

Status & metadata

Table

All components (A-Z)