Theme

npm_versionnpm Paragon package page
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.

Any Paragon component or export may be added to the code example.

Table Props API

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

  • 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">

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.

Any Paragon component or export may be added to the code example.

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

  • 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
const MiyazakiCard = ({ className, original }) => {
const { title, director, release_date } = original;
return (
<Card className={className}>
<Card.ImageCap src="https://picsum.photos/360/200/" srcAlt="Card image" />
<Card.Section title={title}>
<dl>
<dt>Director</dt><dd>{director}</dd>
<dt>Release Date</dt><dd>{release_date}</dd>
</dl>
</Card.Section>
</Card>
);
};

Theme Variables (SCSS)#

$data-table-background-color: $white !default;
$data-table-border: 2px solid $light-300 !default;
$data-table-box-shadow: $box-shadow-sm !default;
$data-table-padding-x: .75rem !default;
$data-table-padding-y: .75rem !default;
$data-table-padding-small: .5rem !default;
$data-table-cell-padding: .5rem .75rem !default;
$data-table-footer-position: center !default;
$data-table-pagination-dropdown-max-height: 60vh !default;
$data-table-pagination-dropdown-min-width: 6rem !default;
$data-table-layout-sidebar-width: 12rem !default;

Props API#

DataTable Props API
  • columns shape {
    Header: elementType | node Required,
    accessor: requiredWhenNot(PropTypes.string, 'Cell'),
    Cell: elementType | node,
    Filter: elementType,
    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: elementType | node Required,
    Cell: elementType | node,
    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: elementType,
    }

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

    Default{}
  • additionalColumns shape {
    id: string Required,
    Header: elementType | node,
    Cell: elementType | 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,
    }
    ,
    selectedRowsOrdered: number[],
    }

    Initial state passed to react-table's documentation https://github.com/TanStack/table/blob/v7/docs/src/pages/docs/api/useTable.md

    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 elementType

    Component to be displayed when the table is empty

    DefaultEmptyTableContent
  • RowStatusComponent elementType

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

    DefaultRowStatus
  • SelectionStatusComponent elementType

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

    DefaultSelectionStatus
  • FilterStatusComponent elementType

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

    DefaultFilterStatus
  • children 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.

  • maxSelectedRows number

    Indicates the max of rows selectable in the table. Requires isSelectable prop

  • onMaxSelectedRows func

    Callback after selected max rows. Requires isSelectable and maxSelectedRows props

TableControlBar Props API
  • className string

    Specifies class name to append to the base element

    Defaultnull
TableFooter Props API
  • children node

    Specifies the content of the TableFooter

    Defaultnull
  • className string

    Specifies class name to append to the base element.

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">

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

  • 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

Usage Insights#

CardView

Project NameParagon VersionInstance Count
frontend-app-admin-portal21.13.13
frontend-app-course-authoring22.6.12
frontend-app-enterprise-public-catalog21.13.12
frontend-app-learning22.3.01

DataTable

Project NameParagon VersionInstance Count
edx-ora221.8.01
frontend-app-admin-portal21.13.126
frontend-app-communications22.0.02
frontend-app-course-authoring22.6.16
frontend-app-ecommerce20.46.31
frontend-app-enterprise-public-catalog21.13.12
frontend-app-gradebook22.1.13
frontend-app-learner-record22.6.11
frontend-app-learning22.3.03
frontend-app-ora-grading21.11.32
frontend-app-publisher20.46.31
frontend-app-support-tools20.46.02

DataTableTable

Project NameParagon VersionInstance Count
edx-ora221.8.01
frontend-app-admin-portal21.13.16
frontend-app-course-authoring22.6.13
frontend-app-ecommerce20.46.31
frontend-app-enterprise-public-catalog21.13.11
frontend-app-gradebook22.1.11
frontend-app-learner-record22.6.11
frontend-app-learning22.3.02
frontend-app-ora-grading21.11.32

Table

Project NameParagon VersionInstance Count
edx-platform2.6.42
frontend-app-admin-portal21.13.11
studio-frontend3.4.81

TableFooter

Project NameParagon VersionInstance Count
frontend-app-course-authoring22.6.11