Data views
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.
The DataTable.Table component expects to receive a react-table instance from the DataTableContext.
- captionDefaultnull
string
|element
- className
string
- data
shape
{}[]
Requiredspecifies 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:
label
(string or element; required) contains the display string for each column's heading.key
(string; required) maps that label to its corresponding datum for each row indata
, to ensure table data are displayed in their appropriate columns.columnSortable
(boolean; optional) specifies at the column-level whether the column is sortable. IfcolumnSortable
istrue
, a sort button will be rendered in the column table heading. It is only required iftableSortable
is set totrue
.onSort
(function; conditionally required) specifies what function is called when a sortable column is clicked. It is only required if the column'scolumnSortable
is set totrue
.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.width
(string; conditionally required) only ifhasFixedColumnWidths
is set totrue
, the<td>
elements'class
attributes will be set to this value. This allows restricting columns to specific widths. See Bootstrap's grid documentation forcol
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)
,[]
Requiredspecifies 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:
label
(string or element; required) contains the display string for each column's heading.key
(string; required) maps that label to its corresponding datum for each row indata
, to ensure table data are displayed in their appropriate columns.columnSortable
(boolean; optional) specifies at the column-level whether the column is sortable. IfcolumnSortable
istrue
, a sort button will be rendered in the column table heading. It is only required iftableSortable
is set totrue
.onSort
(function; conditionally required) specifies what function is called when a sortable column is clicked. It is only required if the column'scolumnSortable
is set totrue
.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.width
(string; conditionally required) only ifhasFixedColumnWidths
is set totrue
, the<td>
elements'class
attributes will be set to this value. This allows restricting columns to specific widths. See Bootstrap's grid documentation forcol
class names that can be used.
The order of objects in
columns
specifies the order of the columns in the table. - headingClassName
string
[]
Default[]Specifies Bootstrap class names to apply to the table heading. Options are detailed in Bootstrap's docs.
- tableSortable
bool
DefaultfalseSpecifies whether the table is sortable. This setting supercedes column-level sortability, so if it is
false
, no sortable components will be rendered. - hasFixedColumnWidths
bool
DefaultfalseSpecifies whether the table's columns have fixed widths. Every element in
columns
must define awidth
if this istrue
. - 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 totrue
. - 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 iftableSortable
is set totrue
. - sortButtonsScreenReaderText
isRequiredIf( PropTypes.shape({ asc: PropTypes.string, desc: PropTypes.string, defaultText: PropTypes.string, }), props => props.tableSortable, )
Default{ asc: 'sort ascending', desc: 'sort descending', defaultText: 'click to sort', }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:
asc
: (string) specifies the screen reader only text for sort buttons in the ascending state.desc
: (string) specifies the screen reader only text for sort buttons in the descending state.defaultText
: (string) specifies the screen reader only text for sort buttons that are not engaged.
It is only required if
tableSortable
is set totrue
.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.
- row
shape
{getRowProps:func
Required,cells:shape
{}[]
Required,id:string
Required,isSelected:bool
,isExpanded:} Requiredbool
,Row data that is received from
react-table
API.
- getCellProps
func
RequiredProps for the td element
- render
func
RequiredFunction that renders the cell contents. Will be called with the string 'Cell'
- column
shape
{cellClassName:} Requiredstring
,Table column
- getHeaderProps
func
RequiredReturns props for the th element
- isSorted
bool
DefaultfalseIndicates whether or not a column is sorted
- render
func
RequiredRenders the header content. Passed the string 'Header'
- isSortedDesc
bool
DefaultfalseIndicates whether the column is sorted in descending order
- getSortByToggleProps
func
Default() => {}Gets props related to sorting that will be passed to th
- canSort
bool
DefaultfalseIndicates whether a column is sortable
- headerClassName
string
DefaultnullClass(es) to be applied to header cells
- 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.
- className
string
The class name for the CardGrid component
- columnSizes
shape
{xs:number
,sm:number
,md:number
,lg:number
,xl:}number
,Default{ xs: 12, lg: 6, xl: 4, }An object containing the desired column size at each breakpoint, following a similar props API as
react-bootstrap/Col
- CardComponent
func
RequiredYour 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'Default'right'If the Cards are selectable this prop determines from which side of the Card to show selection component.
- SkeletonCardComponent
func
Overrides default skeleton card component for loading state in CardView
- skeletonCardCount
number
Default8Customize the number of loading skeleton cards to display in CardView
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#
- 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
,[]
,[]
RequiredDefinition of table columns
- data
shape
{}[]
RequiredData to be displayed in the table
- isSelectable
bool
Defaultfalsetable rows can be selected
- 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
DefaultfalseTable columns can be sorted
- manualSortBy
bool
DefaultfalseIndicates that sorting will be done via backend API. A fetchData function must be provided
- isPaginated
bool
DefaultfalsePaginate the table
- manualPagination
bool
DefaultfalseIndicates that pagination will be done manually. A fetchData function must be provided
- pageCount
requiredWhen(PropTypes.number, 'manualPagination')
- isFilterable
bool
DefaultfalseTable rows can be filtered, using a default filter in the default column values, or in the column definition
- manualFilters
bool
DefaultfalseIndicates that filtering will be done via a backend API. A fetchData function must be provided
- defaultColumnValues
shape
{Filter:}elementType
,Default{}defaults that will be set on each column. Will be overridden by individual column values
- additionalColumns
shape
{id:string
Required,Header:elementType
|node
,Cell:}elementType
|node
,[]
Default[]Actions or other additional non-data columns can be added here
- fetchData
func
DefaultnullFunction that will fetch table data. Called when page size, page index or filters change. Meant to be used with manual filters and pagination
- 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
[]
,Default{}Initial state passed to react-table's documentation https://github.com/TanStack/table/blob/v7/docs/src/pages/docs/api/useTable.md
- initialTableOptions
shape
{}Default{}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
- itemCount
number
RequiredActions 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
Default[]Actions to be performed on selected rows of the table. Called with the selected rows. Only displayed if rows are selected.
- tableActions
shape
{buttonText:string
Required,handleClick:func
Required,className:string
,variant:string
,disabled:} |bool
,func
|element
[]
|func
|element
Default[]Function for rendering custom components, called with the table instance
- numBreakoutFilters
enum
1 | 2 | 3 | 4Default1Number between one and four filters that can be shown on the top row.
- EmptyTableComponent
elementType
DefaultEmptyTableContentComponent to be displayed when the table is empty
- RowStatusComponent
elementType
DefaultRowStatusComponent to be displayed for row status, ie, 10 of 20 rows. Displayed by default in the TableControlBar
- SelectionStatusComponent
elementType
DefaultSelectionStatusComponent to be displayed for selection status. Displayed when there are selected rows and no active filters
- FilterStatusComponent
elementType
DefaultFilterStatusComponent to be displayed for filter status. Displayed when there are active filters.
- children
node
DefaultnullIf children are not provided a table with control bar and footer will be rendered
- showFiltersInSidebar
bool
DefaultfalseIf true filters will be shown on sidebar instead
- dataViewToggleOptions
shape
{isDataViewToggleEnabled:bool
,onDataViewToggle:func
,defaultActiveStateValue:string
,togglePlacement:}string
,Default{ isDataViewToggleEnabled: false, onDataViewToggle: () => {}, defaultActiveStateValue: 'card', togglePlacement: 'left', }options for data view toggle
- disableElevation
bool
DefaultfalseRemove the default box shadow on the component
- renderRowSubComponent
func
A function that will render contents of expanded row, accepts
row
as a prop. - isExpandable
bool
DefaultfalseIndicates whether table supports expandable rows.
- isLoading
bool
DefaultfalseIndicates whether the table should show loading states.
- 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
- className
string
DefaultnullSpecifies class name to append to the base element
- captionDefaultnull
string
|element
- className
string
- data
shape
{}[]
Requiredspecifies 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:
label
(string or element; required) contains the display string for each column's heading.key
(string; required) maps that label to its corresponding datum for each row indata
, to ensure table data are displayed in their appropriate columns.columnSortable
(boolean; optional) specifies at the column-level whether the column is sortable. IfcolumnSortable
istrue
, a sort button will be rendered in the column table heading. It is only required iftableSortable
is set totrue
.onSort
(function; conditionally required) specifies what function is called when a sortable column is clicked. It is only required if the column'scolumnSortable
is set totrue
.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.width
(string; conditionally required) only ifhasFixedColumnWidths
is set totrue
, the<td>
elements'class
attributes will be set to this value. This allows restricting columns to specific widths. See Bootstrap's grid documentation forcol
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)
,[]
Requiredspecifies 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:
label
(string or element; required) contains the display string for each column's heading.key
(string; required) maps that label to its corresponding datum for each row indata
, to ensure table data are displayed in their appropriate columns.columnSortable
(boolean; optional) specifies at the column-level whether the column is sortable. IfcolumnSortable
istrue
, a sort button will be rendered in the column table heading. It is only required iftableSortable
is set totrue
.onSort
(function; conditionally required) specifies what function is called when a sortable column is clicked. It is only required if the column'scolumnSortable
is set totrue
.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.width
(string; conditionally required) only ifhasFixedColumnWidths
is set totrue
, the<td>
elements'class
attributes will be set to this value. This allows restricting columns to specific widths. See Bootstrap's grid documentation forcol
class names that can be used.
The order of objects in
columns
specifies the order of the columns in the table. - headingClassName
string
[]
Default[]Specifies Bootstrap class names to apply to the table heading. Options are detailed in Bootstrap's docs.
- tableSortable
bool
DefaultfalseSpecifies whether the table is sortable. This setting supercedes column-level sortability, so if it is
false
, no sortable components will be rendered. - hasFixedColumnWidths
bool
DefaultfalseSpecifies whether the table's columns have fixed widths. Every element in
columns
must define awidth
if this istrue
. - 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 totrue
. - 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 iftableSortable
is set totrue
. - sortButtonsScreenReaderText
isRequiredIf( PropTypes.shape({ asc: PropTypes.string, desc: PropTypes.string, defaultText: PropTypes.string, }), props => props.tableSortable, )
Default{ asc: 'sort ascending', desc: 'sort descending', defaultText: 'click to sort', }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:
asc
: (string) specifies the screen reader only text for sort buttons in the ascending state.desc
: (string) specifies the screen reader only text for sort buttons in the descending state.defaultText
: (string) specifies the screen reader only text for sort buttons that are not engaged.
It is only required if
tableSortable
is set totrue
.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">
- getCellProps
func
RequiredProps for the td element
- render
func
RequiredFunction that renders the cell contents. Will be called with the string 'Cell'
- column
shape
{cellClassName:} Requiredstring
,Table column
- getHeaderProps
func
RequiredReturns props for the th element
- isSorted
bool
DefaultfalseIndicates whether or not a column is sorted
- render
func
RequiredRenders the header content. Passed the string 'Header'
- isSortedDesc
bool
DefaultfalseIndicates whether the column is sorted in descending order
- getSortByToggleProps
func
Default() => {}Gets props related to sorting that will be passed to th
- canSort
bool
DefaultfalseIndicates whether a column is sortable
- headerClassName
string
DefaultnullClass(es) to be applied to header cells
- headerGroups
shape
{headers:shape
{getHeaderProps:}func
Required,[]
Required,getHeaderGroupProps:}func
Required,[]
Required
- row
shape
{getRowProps:func
Required,cells:shape
{}[]
Required,id:string
Required,isSelected:bool
,isExpanded:} Requiredbool
,Row data that is received from
react-table
API.
- className
string
The class name for the CardGrid component
- columnSizes
shape
{xs:number
,sm:number
,md:number
,lg:number
,xl:}number
,Default{ xs: 12, lg: 6, xl: 4, }An object containing the desired column size at each breakpoint, following a similar props API as
react-bootstrap/Col
- CardComponent
func
RequiredYour 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'Default'right'If the Cards are selectable this prop determines from which side of the Card to show selection component.
- SkeletonCardComponent
func
Overrides default skeleton card component for loading state in CardView
- skeletonCardCount
number
Default8Customize the number of loading skeleton cards to display in CardView
Usage Insights#
CardView
Project Name | Paragon Version | Instance Count | |
---|---|---|---|
frontend-app-admin-portal | 21.13.1 | 3 | |
frontend-app-course-authoring | 22.8.1 | 2 | |
frontend-app-enterprise-public-catalog | 21.13.1 | 2 | |
frontend-app-learning | 22.8.1 | 1 |
DataTable
Project Name | Paragon Version | Instance Count | |
---|---|---|---|
edx-ora2 | 21.8.0 | 1 | |
frontend-app-admin-portal | 21.13.1 | 29 | |
frontend-app-communications | 22.7.0 | 2 | |
frontend-app-course-authoring | 22.8.1 | 6 | |
frontend-app-ecommerce | 20.46.3 | 1 | |
frontend-app-enterprise-public-catalog | 21.13.1 | 2 | |
frontend-app-gradebook | 22.8.1 | 3 | |
frontend-app-learner-record | 22.8.1 | 1 | |
frontend-app-learning | 22.8.1 | 3 | |
frontend-app-ora-grading | 21.11.3 | 2 | |
frontend-app-publisher | 21.13.1 | 1 | |
frontend-app-support-tools | 21.13.1 | 6 |
DataTableTable
Project Name | Paragon Version | Instance Count | |
---|---|---|---|
edx-ora2 | 21.8.0 | 1 | |
frontend-app-admin-portal | 21.13.1 | 8 | |
frontend-app-course-authoring | 22.8.1 | 3 | |
frontend-app-ecommerce | 20.46.3 | 1 | |
frontend-app-enterprise-public-catalog | 21.13.1 | 1 | |
frontend-app-gradebook | 22.8.1 | 1 | |
frontend-app-learner-record | 22.8.1 | 1 | |
frontend-app-learning | 22.8.1 | 2 | |
frontend-app-ora-grading | 21.11.3 | 2 | |
frontend-app-support-tools | 21.13.1 | 1 |
Table
Project Name | Paragon Version | Instance Count | |
---|---|---|---|
edx-platform | 2.6.4 | 2 | |
frontend-app-admin-portal | 21.13.1 | 1 | |
studio-frontend | 3.4.8 | 1 |
TableFooter
Project Name | Paragon Version | Instance Count | |
---|---|---|---|
frontend-app-course-authoring | 22.8.1 | 1 |