Data table
A data table is used to display and allow interaction with data in a structured way.
A minimal version of the demo looks like this.
<DataTable>
<TableHead>
<DataTableRow>
<DataTableColumnHeader>First name</DataTableColumnHeader>
</DataTableRow>
</TableHead>
<TableBody>
<DataTableRow>
<DataTableCell>Onyekachukwu</DataTableCell>
</DataTableRow>
</TableBody>
<TableFoot>
<DataTableRow>
<DataTableCell>Footer content</DataTableCell>
</DataTableRow>
</TableFoot>
</DataTable>
Usage
When to use
- Working with complex data. Use a data table whenever a user needs to look at or work with complex data.
When not to use
- Summarizing data. Don't use a data table if a user doesn't need to look at all the data, but instead needs a summary. An alternative is a summary with optional access to the source data table if needed.
Options
Sorting
- Data table items can be sorted by different columns by clicking on the sort icon in a column header.
- Always allow sorting of items by different columns unless the order is specific and shouldn't be changed.
Filtering: Inline
- Use inline filters in complex interfaces to offer filtering functionality without extra controls outside of the table.
- If filtering is the main functionality of the data table, consider offering standalone filters.
Fixed header
- Use a fixed header in data tables that are used to browse a lot of data. Fixed headers stay in view and make it easier to understand what cells contain.
Fixed columns
- Use fixed columns in dense interfaces where the table might need to be scrolled horizontally.
- Any number of columns can be fixed, but usually a single column is enough, as long as it provides a clear reference for the rest of the row.
Expandable rows
- Use expandable rows if there's more useful information that doesn't fit well into columns, like paragraphs of text, images, or video.
Selectable rows
- Use selectable rows if a user can perform batch actions on rows in the data table, like selecting several rows and exporting or deleting them.
Draggable rows
- Use draggable rows if the order of rows in the data table has a meaningful impact. With draggable rows, a user can drag rows to change the order.
Bordered cells
- Use bordered cells when showing complex data that might have similar values, like long numbers, to help a user visually scan data values.
Built-in styles
- A data table offers several built-in text styles.
- Use the built-in styles to help offer a consistent data table experience across DHIS2 apps.
Large cells
- Use large cells can be used for data tables that will don't show a lot of rows.
- Large cells can help users scan and work with a few rows.
Patterns
Patterns are common ways of achieving some functionality. Patterns aren't offered as prebuilt components, but should be built and tweaked according to the use case.
Pagination
==TODO: example==
- Use the
Pagination
component in a data table footer to allow navigation between pages.
Search
==TODO: example==
- A text
Input
offers a quick way to search for items in a data table. - Make it clear what attributes the search applies to with placeholder text, like Search by name or code.
Filtering: Standalone
==TODO: example==
- Use standalone filters when the filtering functionality is likely to be used as the main use case for the data table.
- A common design is to use a
Select
control for each column, as in the demo above.
Row actions
==TODO: example==
- Row actions are often shown as buttons in the last column of a data table.
- Use row actions to offer actions for every row in the table.
- Row actions can add a lot of complexity to a page, so don't show too many buttons. It often makes sense to offer secondary actions through a context menu button.
Status
==TODO: example==
- Use a tag to show a status for every row in a data table.
- Make sure every row has a status, even if a tag shows None or No status. Don't leave status cells blank.
State: Empty
==TODO: example==
- Use the data table empty state to explain why there isn't anything to show and to offer a way of fixing that, if it's a problem.
- In the example above, the empty data table tells the user that there aren't any patients and offers them a shortcut to start registering.
- A data table empty state should be customized for each use case.
Guidelines
Using and combining options
- Only use the options that target a specific user need for that data table.
- Avoid using
expandable
andreorderable
rows together. Dragging and dropping doesn't work well when each row can have a different height. - Avoid using
expandable
andbordered
rows together. The cell borders make the relationship between the row and the expanded content unclear.
API Reference
DataTableCell
Usage
To use DataTableCell
, you can import the component from the @dhis2/ui
library
import { DataTableCell } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
active | boolean | To toggle border color, for example for editing | ||
align | 'left' │ 'center' │ 'right' | 'left' | ||
backgroundColor | string | Sets background color of the cell. Disables dynamic background colors from active, hover, and selected states | ||
bordered | boolean | |||
children | node | |||
className | string | |||
colSpan | string | |||
dataTest | string | 'dhis2-uicore-datatablecell' | ||
error | custom | Mutually exclusive with muted and valid | ||
fixed | boolean | When true a TableHeaderCell with sticky positioning will be rendered | ||
large | boolean | |||
left | custom | 'auto' | Required when fixed | |
muted | custom | Mutually exclusive with error and valid | ||
role | string | |||
rowSpan | string | |||
scope | string | |||
staticStyle | boolean | Surpress hover and active event styles | ||
tag | 'td' │ 'th' | Render a TableDataCell or TableHeaderCell respectively | ||
valid | custom | Mutually exclusive with error and muted | ||
width | custom | 'auto' | Required when fixed | |
onClick | function |
DataTable
Usage
To use DataTable
, you can import the component from the @dhis2/ui
library
import { DataTable } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | Should be <DataTableHead> , <DataTableBody> , and <DataTableFoot> components | ||
className | string | |||
dataTest | string | 'dhis2-uicore-datatable' | ||
layout | 'auto' │ 'fixed' │ 'initial' │ 'inherit' | 'auto' | Sets the datatable-layout property. Switching to fixed can prevent styleissues when dealing with a datatable with multiple frozen columns or when dealing with filter elements in the datatable headers. | |
role | string | |||
scrollHeight | string | Sets max-height of scrollbox | ||
scrollWidth | string | Sets max-width of scrollbox | ||
width | string | '100%' | Sets the width property. Providing an explicit width can prevent styleissues when dealing with horizontally scrolling datatables with a fixed layout. |
StackedTableBody
Usage
To use StackedTableBody
, you can import the component from the @dhis2/ui
library
import { StackedTableBody } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | |||
className | string | |||
dataTest | string | 'dhis2-uicore-stackedtablebody' |
StackedTableCellHead
Usage
To use StackedTableCellHead
, you can import the component from the @dhis2/ui
library
import { StackedTableCellHead } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | string | '' | ||
className | string | |||
colSpan | string | |||
dataTest | string | 'dhis2-uicore-stackedtablecellhead' | ||
rowSpan | string |
StackedTableCell
Usage
To use StackedTableCell
, you can import the component from the @dhis2/ui
library
import { StackedTableCell } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | |||
className | string | |||
colSpan | string | |||
column | number | |||
dataTest | string | 'dhis2-uicore-stackedtablecell' | ||
headerLabels | arrayOf(string) | [] | ||
hideTitle | boolean | |||
rowSpan | string | |||
title | string |
StackedTableFoot
Usage
To use StackedTableFoot
, you can import the component from the @dhis2/ui
library
import { StackedTableFoot } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | |||
className | string | |||
dataTest | string | 'dhis2-uicore-stackedtablefoot' |
StackedTableHead
Usage
To use StackedTableHead
, you can import the component from the @dhis2/ui
library
import { StackedTableHead } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | |||
className | string | |||
dataTest | string | 'dhis2-uicore-stackedtablehead' |
StackedTableRowHead
Usage
To use StackedTableRowHead
, you can import the component from the @dhis2/ui
library
import { StackedTableRowHead } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | |||
className | string | |||
dataTest | string | 'dhis2-uicore-stackedtablerowhead' |
StackedTableRow
Usage
To use StackedTableRow
, you can import the component from the @dhis2/ui
library
import { StackedTableRow } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | |||
className | string | |||
dataTest | string | 'dhis2-uicore-stackedtablerow' |
StackedTable
Usage
To use StackedTable
, you can import the component from the @dhis2/ui
library
import { StackedTable } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | |||
className | string | |||
dataTest | string | 'dhis2-uicore-stackedtable' | ||
headerLabels | arrayOf(string) | Labels for columns. Use an empty string for a column without a header. |
Table
Usage
To use Table
, you can import the component from the @dhis2/ui
library
import { Table } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | * | ||
className | string | |||
dataTest | string |
TableBody
Usage
To use TableBody
, you can import the component from the @dhis2/ui
library
import { TableBody } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | Should be <TableRow> components | ||
className | string | |||
dataTest | string | 'dhis2-uicore-tablebody' | ||
role | string |
TableCellHead
Usage
To use TableCellHead
, you can import the component from the @dhis2/ui
library
import { TableCellHead } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | |||
className | string | |||
colSpan | string | |||
dataTest | string | 'dhis2-uicore-tablecellhead' | ||
dense | boolean | Uses less padding and height for information-dense layouts | ||
role | string | |||
rowSpan | string |
TableCell
Usage
To use TableCell
, you can import the component from the @dhis2/ui
library
import { TableCell } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | |||
className | string | |||
colSpan | string | |||
dataTest | string | 'dhis2-uicore-tablecell' | ||
dense | boolean | Usees less padding and height for information-dense layouts | ||
role | string | |||
rowSpan | string |
TableFoot
Usage
To use TableFoot
, you can import the component from the @dhis2/ui
library
import { TableFoot } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | Should be <TableRow> components | ||
className | string | |||
dataTest | string | 'dhis2-uicore-tablefoot' | ||
role | string |
TableHead
Usage
To use TableHead
, you can import the component from the @dhis2/ui
library
import { TableHead } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | Should be <TableRowHead> components | ||
className | string | |||
dataTest | string | 'dhis2-uicore-tablehead' | ||
role | string |
TableRowHead
Usage
To use TableRowHead
, you can import the component from the @dhis2/ui
library
import { TableRowHead } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | Should be <TableCellHead> components | ||
className | string | |||
dataTest | string | 'dhis2-uicore-tablerowhead' | ||
role | string | |||
suppressZebraStriping | boolean | Disables the default row striping for this row |
TableRow
Usage
To use TableRow
, you can import the component from the @dhis2/ui
library
import { TableRow } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | Should be <TableCell> or <TableCellHead> components | ||
className | string | |||
dataTest | string | 'dhis2-uicore-tablerow' | ||
role | string | |||
suppressZebraStriping | boolean | Disables the default row striping for this row |
Table
Usage
To use Table
, you can import the component from the @dhis2/ui
library
import { Table } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | Should be <TableHead> , <TableBody> , and <TableFoot> components | ||
className | string | |||
dataTest | string | 'dhis2-uicore-table' | ||
role | string | |||
suppressZebraStriping | boolean | Remove the default striping on alternating rows |
DataTableColumnHeader
Usage
To use DataTableColumnHeader
, you can import the component from the @dhis2/ui
library
import { DataTableColumnHeader } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
align | 'left' │ 'center' │ 'right' | |||
children | node | |||
className | string | |||
colSpan | string | |||
dataTest | string | 'dhis2-uicore-datatablecellhead' | ||
filter | custom(function) | The filter element (JSX), required when onFilterIconClick or showFilter are present | ||
fixed | boolean | |||
large | boolean | |||
left | custom(function) | Left or top required when fixed | ||
name | string | Can be used to match a column with a property name | ||
role | string | |||
rowSpan | string | |||
scope | string | |||
showFilter | custom(function) | |||
sortDirection | custom(function) | |||
sortIconTitle | string | |||
top | custom(function) | Left or top required when fixed | ||
width | string | |||
onFilterIconClick | custom(function) | |||
onSortIconClick | custom(function) | Sort icon click callback with nextSortDirection and name in payload |
DataTableRow
Usage
To use DataTableRow
, you can import the component from the @dhis2/ui
library
import { DataTableRow } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | Should be <DataTableCell> or <DataTableCellHead> components | ||
className | string | |||
dataTest | string | 'dhis2-uicore-datatablerow' | ||
draggable | boolean | Renders and additional table cell with drag icon and applies draggable styles | ||
expandableContent | custom(function) | This content will be rendered into an additional row with fullwidth cell and the presence of this prop will display an additional table cell with expand icon | ||
expanded | boolean | Toggles expand icon (up/down) and expandable content visibility | ||
role | string | |||
selected | boolean | Adds a green background color | ||
onExpandToggle | custom(function) | Callback for expand icon cell clicks |
TableBody
Usage
To use TableBody
, you can import the component from the @dhis2/ui
library
import { TableBody } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | Should be <TableRow> components | ||
className | string | |||
dataTest | string | 'dhis2-uicore-tablebody' | ||
loading | boolean | |||
role | string |
TableFoot
Usage
To use TableFoot
, you can import the component from the @dhis2/ui
library
import { TableFoot } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | Should be <TableRow> components | ||
className | string | |||
dataTest | string | 'dhis2-uicore-tablefoot' | ||
role | string |
TableHead
Usage
To use TableHead
, you can import the component from the @dhis2/ui
library
import { TableHead } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | Should be <TableRowHead> components | ||
className | string | |||
dataTest | string | |||
role | string |
TableRow
Usage
To use TableRow
, you can import the component from the @dhis2/ui
library
import { TableRow } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
children | node | Should be <TableDataCell> or <TableDataCellHead> components | ||
className | string | |||
dataTest | string | 'dhis2-uicore-tablerow' | ||
draggable | boolean | Applies draggable cursor styles | ||
role | string | |||
selected | boolean | Sets a selected (teal) background color |
Table
Usage
To use Table
, you can import the component from the @dhis2/ui
library
import { Table } from '@dhis2/ui'
Props
Name | Type | Default | Required | Description |
---|---|---|---|---|
borderless | boolean | Removes border from the table | ||
children | node | Should be <TableHead> , <TableBody> , and <TableFoot> components | ||
className | string | |||
dataTest | string | 'dhis2-uicore-table' | ||
layout | 'auto' │ 'fixed' │ 'initial' │ 'inherit' | 'auto' | Sets the table-layout property. Switching to fixed can prevent styleissues when dealing with a table with multiple frozen columns or when dealing with filter elements in the table headers. | |
role | string | |||
width | string | '100%' | Sets the width property. Providing an explicit width can prevent styleissues when dealing with horizontally scrolling tables with a fixed layout. |