Datatable

Datatables are designed to present information consistently, facilitating easy data comparison

This article is quite lengthy. To quickly find the information you're looking for, consider using the intelligent search.

Overview

Datatables are a core component of our products, designed to present information in a structured grid format with rows and columns. This format simplifies data comprehension and helps users in managing their content

Datatable should be used:

• to display complex data in an easy-to-scan way,

• if users need to sort on multiple columns,

• if users need column titles to make sure the context and content are clear,

• if data needs to be displayed in a controlled way (using pre-formatted cells).

Datatable should not be used:

• To display a collection of items with an elaborate layout (use Datalist),

• To highlight part of a data set (use Data Visualization).

• If data is not structured or with variable content

Having trouble deciding between Datalist and Datatable? Head over to the Displaying data pattern

Design Guidelines

1. Title : clearly states the content of the datatable.

For further details on each listed element, please refer to the dedicated subpage.

2. Toolbar

3. Columns

4. Rows

5. Scrollbar

6. Footer and pagination

Toolbar

The toolbar includes a search bar, filters, and options for managing displays and adding content. Available elements include:

• Search (standard or column-specific with a drop-down selector)

• Item count (mandatory)

• Column management

• Density management (mandatory)

• Export (only on visible data)

• Action button

• Refresh (disabled while reordering)

• Filters

For 3 or fewer filters, use the Quick Filters layout. For more than 3 filters, use the Filters Drawer, which opens on the right side of the screen.

Columns

Column width is defined by the largest content (cell and header) within a limit of 500 px. The width is overridable. Otherwise, the content is cut with an ellipsis.

Datatables are sorted by default. Feature teams define which column is used to sort the datatable. It can be sorted by identifier, by date/time, by status... The sort must be visible, on the left side, to help users understand how data is sorted.

• At least one column must provide a sortable property.

• Sortable properties are exclusive. It means if two or more columns provide a sortable property, they can not be active at the same time.

• Sort property can only be deactivated when search is active. When user type for an item in the search bar, sort is not mandatory.

Rows

A row displays information related to a single item.

Row States :

• Default: row is clear, and actions are available. This is the standard row behavior.

• Disabled: row is greyed out, and actions are unavailable. For example, you may use it when a product is rejected, and no action can be taken to change its status.

• Highlighted: row has a ribbon to highlight it

• Dimmed: row is greyed out, but actions are still available. For example, you may use it when a product has been excluded from a selection, but you can reactivate it later.

Rows Types

• Selection : rows are selectable and selection is managed with the bulk.

• Reorder: rows can be reordered by user action. The drag functionality is shown but disabled when the table contains only a single row.

In our products, we commonly utilize the 'reorder' datatable type to prioritize custom rules based on their importance. It's essential to remind users, in such scenarios, their rules will be processed by their ranking.

When using the reorder function, datatable cannot have pagination.

Rows Size

Rows are available in three sizes: compact, default (used by default), and comfortable. Users can change size with the density button in the filter bar. This option is automatically handled.

Cells

They are 9 Cell Types for Datatables :

1. TextCellContent

• Description: Displays text with optional subtext, media, actions, and a trailing icon for tooltips.

• Options:

  • Sizes: Default / Comfortable / Compact

  • Actions: No action, expandable, view, edit, or external link.

  • Media: Available for Default and Comfortable sizes.

  

  TextCellContent

2. BadgeCellContent

• Description: Displays up to 3 badges, each with an optional tooltip. More than 3 badges are expandable.

• Options:

  • Statuses: Custom badge statuses.

BadgeCellContent

3. DateCellContent

• Description: Displays dates with optional subtext, statuses, and a trailing icon for additional information (e.g., late, help).

• Options:

  • Expandable, subtext, trailing icon, and statuses.

DateCellContent

4. IconListCellContent

• Description: Displays a list of icons, each with a name, status, and automatic tooltip.

• Options:

  • Icon Statuses: Pending (purple), Warning (orange), Error (red), Success (green), Default (grey).

  • Icons should never be empty; use disabled status if needed.

IconListCellContent

5. MonetaryCellContent

• Description: Displays numeric monetary values, aligned to the right.

• Options:

  • Expandable or edit actions, optional subtext, icons, and various statuses.

  • Currency symbol can be placed before or after the number.

MonetaryCellContent

6. NumericCellContent

• Description: Displays numeric content (non-currency), aligned to the right.

• All numeric content HAVE to be displayed with this cell type ; not as paragraph

• Options:

  • Same options as MonetaryCellContent but without the currency symbol.

7. ParagraphCellContent

• Description: Displays a paragraph with automatic truncation to 2 lines.

• Options:

  • No statuses, subtext, or actions; solely for displaying long text.

ParagraphCellContent

8. RatingCellContent

• Description: Displays rating content with optional subtext, expandable action, or tooltip.

• Options:

  • Variants: Rating with stars or numeric text-only.

  • Same statuses as TextCellContent.

RatingCellContent

9. StatusCellContent

• Description: Displays a single status with optional tooltip.

• Options:

  • Icon Statuses: Pending (purple), Warning (orange), Error (red), Success (green), Default (grey).

  • Can be expandable.

StatusCellContent

Footer & pagination

On Datatable's footer, users can manage pagination :

• Manage number of items per page

• Navigate through the pages

Each project has the flexibility to set its own pagination thresholds, which should be determined based on the average number of results.

We recommend using thresholds of 50, 100, and 200 items per page.

If your datatable is expected to display a smaller number of items, you can opt for lower thresholds.

Navigation elements are consistently visible on the datatable.

• In cases where the current page corresponds to either the first or last page, the pagination controls are displayed, but the navigation buttons are disabled.

• In cases where the current number of item is lower than the first threshold, the pagination controls are displayed, but the navigation buttons are disabled.

When your Datatable contains a significant amount of data, such as more than 1,234 results, we display a universally formatted number, typically around +1,000.

Behaviors & Interactions

The datatable allows users to:

• Sort by column headers

• Filter data subsets

• Perform single or bulk actions

• Export data in various formats

• Add or reorder data

• Navigate via pagination

Default item

In a datatable, only one item can be designated as the 'default.'

'Default' status is designed with a simple "Default" mark inlined with the Label of the cell.

Expand cells

Cells may contain extensive or highly detailed information that could potentially overwhelm the datatable's presentation. But also, opening a separate detailed page might appear excessive. To strike a balance, we have introduced 'expand' properties for select cells.

Expandable cells are recognized with a chevron. Extra content is displayed in a popover cell. Content can be structured and with a button if needed.

Actions on a Datatable

Datatables support bulk and individual actions, with varied behavior based on user interactions.

To get more details about a row, the first cell ("TextCellContent") must have either the "view" action (open object) or "external link" action (open in a new window). In these cases, the first action in the action menu should always be "View Details."

Below are listed all ways we design action, wether its individual or bulk actions :

Individual action

Individual quick actions for a single row are available to users, these actions are consistently presented at the end of the row. Three options are available :

• Actions displayed as icon buttons for common actions such as Download, Delete, View, Copy, etc. (Must be IconButton in Secondary Variant)

• Actions displayed as secondary buttons for less common actions that may not be easily understood through icons. (Must be Button in Secondary Variant)

• Actions accessible via an action menu for multiple choice of actions.

Bulk actions

Datatable enables users to select individual rows or multiple rows for performing actions.

Once selected, a bulk action bar will appear, offering a single action (primary button) or more action options (button group). Actions listed on the bulk bar actions must always remain the same ; they cannot change based on the selection or filters.

The selection bar allows to quickly select all items in the dataset, all items on the current page, or to deselect all items. However, once all items are selected in a datatable through this option, individual deselection is not possible.

Users can select all elements in a filtered dataset by first applying a filter to the data and then using the 'select all from this page' option.

Scrolling

Horizontal

When the content of a row is longer than the width of the panel, a floating trailing action is displayed. It ensures the user can perform an action on a row without scrolling.

Fixed header

The column header is pinned while scrolling to ensure the readability of the cell content. The horizontal scrollbar is pinned to the bottom of the viewport to ensure it will always be visible and easily reached.

Loading

When datatable's items are loading :

Skeleton loading is fully automated for Datatable. Learn more about Loading patterns

Empty state

Empty state behavior and microcopy are automatically handled.

Content for any other type of empty state has to be defined for each project.

The toolbar (with the options you chose to add) is displayed in disabled mode, and the primary action is disabled. The same action is moved to the empty state.

The empty state action is the same as the toolbar's, but you may override it. Learn more about writing empty states