DataTable

Anatomy

[WIP image]

Guidelines

Tables are used to display, organize, compare, or format tabular data. Our DataTable is an opinionated and custom table built for users to multiselect rows, sort, and filter the data to their needs. While the DataTable is intended for more complex datasets with multiple fields, it can still be used for simple sets.

Tables for layout

Historically, HTML tables were once used to arrange elements on a webpage before modern CSS layout tools like flexbox and grid existed. Never use the DataTable or any table for layout purposes. We provide components specialized in building layouts, such as the Box and Grid. For more information and the full list of available components, see our "Layout" section under "Components."

DataTable features

The DataTable includes, but is not limited to, the following list of features.

• Pagination
• Row selection
• Search and filtering
• Sorting

We recommend only adding the most necessary features as too many options may be overwhelming for users. For the complete list of features, see Behaviors.

Best practices

Column count

It's not uncommon for more complex datasets to include more fields. These fields are represented by additional columns. The more columns that are included by default, the more difficult it becomes for the user to understand the data presented. Keep only the minimum amount of columns necessary for data to be visible and readable. Allow users the option to show and hide extra columns as necessary.

Be aware that horizontal scrolling is only available for non-fixed DataTables.

Types

Appearance

Layout

Layout determines how the DataTable reacts to its content. By default, tables are fixed in size and cells will not accommodate their content. Use fixed layouts for predictable table sizing.

Auto layout allows cells to accommodate their content size and enables horizontal scrolling. Use auto layouts when column content must be easily readable.

Columns

Width

Column widths may be customized to defined widths or constrained to minimum and maximum width values.

Rows

Highlighting

Highlighting changes a row's background color on mouse hover. Rows are highlighted automatically when they're selectable, but this can be manually enabled on non-selectable rows.

Styles

In addition to the base styles, the DataTable includes two additional row styles: striped and borderless.

Striped style alternates between two neutral background colors to improve the table's readability. This can be helpful for tables with large amounts of data, especially where infinite scrolling is enabled.

Borderless style removes the border between rows. This can be used for a cleaner presentation on tables with smaller datasets.

Behaviors

States

Filter

Filters let users narrow down results by selecting from predefined options, such as a status or category. Filters appear in the table header and can be combined to refine the data shown.

Infinite scrolling

Enabling infinite scrolling (virtualization) allows the table to load large datasets incrementally without a drop in performance as the user scrolls. This can be used an alternative to pagination.

Pagination

Pagination allows users to handle large datasets by separating them into different pages. Controls are displayed under the table and allow the user to select how many results are displayed per page.

Search

Search enables users to filter table data by keyword. The search input is located in the table header and filters across all columns by default. For large datasets, use manual (server-side) search to avoid performance issues.

Columns

Column management

Column settings allow users to show and show columns as needed. Extra columns are accessed through a dropdown menu within the table header.

Column span

Cells may span multiple columns if necessary. This can be used to show that information may not be available or communicate inline status messages about the associated entry.

Sorting

Column sorting allows users the flexibility to organize data. Sorting can be done either by activating a column header or selecting options from the "Sort" dropdown in the table header. Sorting is handled in either ascending or descending order.

Rows

Actions

Actions such as editing, deleting, or viewing row details can be performed on individual rows. Row actions are placed within a dropdown menu in the last cell of each row.

Bulk actions

Bulk actions appear in the table header when one or more rows are selected. The main, promoted action renders as a button separate from the actions within the dropdown button.

Expansion

Similar to an accordion, row expansion displays additional information about the row directly under it without forcing the user to navigate away from the table. Rows that can be expanded are denoted by an expansion toggle icon.

Selection

Row selection allows users to pick one or more rows to act on. Selected rows are visually highlighted with a checked input and different background color. Row selection allows users to perform bulk actions on multiple entries at once.

Content

Caption

DataTable captions are important for providing assistive technology information about the table's purpose and the type of data it contains. Short, descriptive nouns or noun phrases work best for captions.

Note: Captions are not visible to the user but are required for displaying the table.

Column headers

Column headers should clearly describe the data in each column. Write headings in sentence case and avoid abbreviations where possible.

Empty states

Provide a clear and meaningful Empty State message and action when no data is available. This ensures users that the component is functioning correctly but may need data or user attention.