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.

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

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 style issues 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 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

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 style issues 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 style issues when dealing with horizontally scrolling tables with a fixed layout.