Skip to main content

Data table

A data table is used to display and allow interaction with data in a structured way.

Demo

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

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

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

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

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

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

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

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

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

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

Demo
  • 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.

==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 and reorderable rows together. Dragging and dropping doesn't work well when each row can have a different height.
  • Avoid using expandable and bordered 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

NameTypeDefaultRequiredDescription
activebooleanTo toggle border color, for example for editing
align'left' │ 'center' │ 'right''left'
backgroundColorstringSets background color of the cell. Disables dynamic background colors from active, hover, and selected states
borderedboolean
childrennode
classNamestring
colSpanstring
dataTeststring'dhis2-uicore-datatablecell'
errorcustomMutually exclusive with muted and valid
fixedbooleanWhen true a TableHeaderCell with sticky positioning will be rendered
largeboolean
leftcustom'auto'Required when fixed
mutedcustomMutually exclusive with error and valid
rolestring
rowSpanstring
scopestring
staticStylebooleanSurpress hover and active event styles
tag'td' │ 'th'Render a TableDataCell or TableHeaderCell respectively
validcustomMutually exclusive with error and muted
widthcustom'auto'Required when fixed
onClickfunction

DataTable

Usage

To use DataTable, you can import the component from the @dhis2/ui library

import { DataTable } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennodeShould be <DataTableHead>, <DataTableBody>, and <DataTableFoot> components
classNamestring
dataTeststring'dhis2-uicore-datatable'
layout'auto' │ 'fixed' │ 'initial' │ 'inherit''auto'Sets the datatable-layout property. Switching to fixed can prevent style
issues when dealing with a datatable with multiple frozen columns or when dealing
with filter elements in the datatable headers.
rolestring
scrollHeightstringSets max-height of scrollbox
scrollWidthstringSets max-width of scrollbox
widthstring'100%'Sets the width property. Providing an explicit width can prevent style
issues 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

NameTypeDefaultRequiredDescription
childrennode
classNamestring
dataTeststring'dhis2-uicore-stackedtablebody'

StackedTableCellHead

Usage

To use StackedTableCellHead, you can import the component from the @dhis2/ui library

import { StackedTableCellHead } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrenstring''
classNamestring
colSpanstring
dataTeststring'dhis2-uicore-stackedtablecellhead'
rowSpanstring

StackedTableCell

Usage

To use StackedTableCell, you can import the component from the @dhis2/ui library

import { StackedTableCell } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennode
classNamestring
colSpanstring
columnnumber
dataTeststring'dhis2-uicore-stackedtablecell'
headerLabelsarrayOf(string)[]
hideTitleboolean
rowSpanstring
titlestring

StackedTableFoot

Usage

To use StackedTableFoot, you can import the component from the @dhis2/ui library

import { StackedTableFoot } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennode
classNamestring
dataTeststring'dhis2-uicore-stackedtablefoot'

StackedTableHead

Usage

To use StackedTableHead, you can import the component from the @dhis2/ui library

import { StackedTableHead } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennode
classNamestring
dataTeststring'dhis2-uicore-stackedtablehead'

StackedTableRowHead

Usage

To use StackedTableRowHead, you can import the component from the @dhis2/ui library

import { StackedTableRowHead } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennode
classNamestring
dataTeststring'dhis2-uicore-stackedtablerowhead'

StackedTableRow

Usage

To use StackedTableRow, you can import the component from the @dhis2/ui library

import { StackedTableRow } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennode
classNamestring
dataTeststring'dhis2-uicore-stackedtablerow'

StackedTable

Usage

To use StackedTable, you can import the component from the @dhis2/ui library

import { StackedTable } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennode
classNamestring
dataTeststring'dhis2-uicore-stackedtable'
headerLabelsarrayOf(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

NameTypeDefaultRequiredDescription
childrennode*
classNamestring
dataTeststring

TableBody

Usage

To use TableBody, you can import the component from the @dhis2/ui library

import { TableBody } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennodeShould be <TableRow> components
classNamestring
dataTeststring'dhis2-uicore-tablebody'
rolestring

TableCellHead

Usage

To use TableCellHead, you can import the component from the @dhis2/ui library

import { TableCellHead } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennode
classNamestring
colSpanstring
dataTeststring'dhis2-uicore-tablecellhead'
densebooleanUses less padding and height for information-dense layouts
rolestring
rowSpanstring

TableCell

Usage

To use TableCell, you can import the component from the @dhis2/ui library

import { TableCell } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennode
classNamestring
colSpanstring
dataTeststring'dhis2-uicore-tablecell'
densebooleanUsees less padding and height for information-dense layouts
rolestring
rowSpanstring

TableFoot

Usage

To use TableFoot, you can import the component from the @dhis2/ui library

import { TableFoot } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennodeShould be <TableRow> components
classNamestring
dataTeststring'dhis2-uicore-tablefoot'
rolestring

TableHead

Usage

To use TableHead, you can import the component from the @dhis2/ui library

import { TableHead } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennodeShould be <TableRowHead> components
classNamestring
dataTeststring'dhis2-uicore-tablehead'
rolestring

TableRowHead

Usage

To use TableRowHead, you can import the component from the @dhis2/ui library

import { TableRowHead } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennodeShould be <TableCellHead> components
classNamestring
dataTeststring'dhis2-uicore-tablerowhead'
rolestring
suppressZebraStripingbooleanDisables 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

NameTypeDefaultRequiredDescription
childrennodeShould be <TableCell> or <TableCellHead> components
classNamestring
dataTeststring'dhis2-uicore-tablerow'
rolestring
suppressZebraStripingbooleanDisables 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

NameTypeDefaultRequiredDescription
childrennodeShould be <TableHead>, <TableBody>, and <TableFoot> components
classNamestring
dataTeststring'dhis2-uicore-table'
rolestring
suppressZebraStripingbooleanRemove 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

NameTypeDefaultRequiredDescription
align'left' │ 'center' │ 'right'
childrennode
classNamestring
colSpanstring
dataTeststring'dhis2-uicore-datatablecellhead'
filtercustom(function)The filter element (JSX), required when onFilterIconClick or showFilter are present
fixedboolean
largeboolean
leftcustom(function)Left or top required when fixed
namestringCan be used to match a column with a property name
rolestring
rowSpanstring
scopestring
showFiltercustom(function)
sortDirectioncustom(function)
sortIconTitlestring
topcustom(function)Left or top required when fixed
widthstring
onFilterIconClickcustom(function)
onSortIconClickcustom(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

NameTypeDefaultRequiredDescription
childrennodeShould be <DataTableCell> or <DataTableCellHead> components
classNamestring
dataTeststring'dhis2-uicore-datatablerow'
draggablebooleanRenders and additional table cell with drag icon and applies draggable styles
expandableContentcustom(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
expandedbooleanToggles expand icon (up/down) and expandable content visibility
rolestring
selectedbooleanAdds a green background color
onExpandTogglecustom(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

NameTypeDefaultRequiredDescription
childrennodeShould be <TableRow> components
classNamestring
dataTeststring'dhis2-uicore-tablebody'
loadingboolean
rolestring

TableFoot

Usage

To use TableFoot, you can import the component from the @dhis2/ui library

import { TableFoot } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennodeShould be <TableRow> components
classNamestring
dataTeststring'dhis2-uicore-tablefoot'
rolestring

TableHead

Usage

To use TableHead, you can import the component from the @dhis2/ui library

import { TableHead } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennodeShould be <TableRowHead> components
classNamestring
dataTeststring
rolestring

TableRow

Usage

To use TableRow, you can import the component from the @dhis2/ui library

import { TableRow } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennodeShould be <TableDataCell> or <TableDataCellHead> components
classNamestring
dataTeststring'dhis2-uicore-tablerow'
draggablebooleanApplies draggable cursor styles
rolestring
selectedbooleanSets 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

NameTypeDefaultRequiredDescription
borderlessbooleanRemoves border from the table
childrennodeShould be <TableHead>, <TableBody>, and <TableFoot> components
classNamestring
dataTeststring'dhis2-uicore-table'
layout'auto' │ 'fixed' │ 'initial' │ 'inherit''auto'Sets the table-layout property. Switching to fixed can prevent style
issues when dealing with a table with multiple frozen columns or when dealing
with filter elements in the table headers.
rolestring
widthstring'100%'Sets the width property. Providing an explicit width can prevent style
issues when dealing with horizontally scrolling tables with a fixed layout.