DataTable
Description
DataTable is a complex component designed for managing complex data grids.
Appearance
Types
Our design system has two table types:
- Primary table is the foundational table type for displaying large data volumes and complex functionality.
- Secondary table is a table type designed for compactly displaying a small amount of data within widgets and cards. These tables usually have a limited set of features, such as non-interactive sort indicators.
Paddings
You can make a primary table more compact by using the compact
property, which reduces left and right cell paddings to --spacing-2x
.
When displaying a table in a card, increase left and right cell paddings to --spacing-5x
. In code, this can be enabled with the sideIndents="wide"
property: find more details in the Card layout for table example.
Table content styles
Content | Styles and tokens |
---|---|
Primary text | Use --fs-200 and --lh-200 tokens for font-size and line-height respectively, and --text-primary token for color. |
Secondary text | Use --text-secondary token for color. |
Icon, either next to the text or standalone | Use M size and --icon-secondary-neutral token for color. |
Table header
Tooltip
You can use Tooltip to display additional information about a column.
Long titles
By default, long column titles wrap to the next line.
Alternatively, if the space is limited, you can disable text wrap and truncate the title with Ellipsis, showing the full text on hover.
Sticky header
You can make the table header sticky
, so that it stays visible when scrolling long tables.
TIP
Sticky header shouldn't have a shadow during scrolling.
Multi-level header
Column headings can be grouped, resulting in a multi-level table header.
Sorting
For detailed information on sorting columns in the table, refer to Table controls.
Row states
Hovering highlights information in large data volumes, making it easier to perform actions such as reading, deleting, or opening.
- The row changes to the
hover
state when you hover over any part of it. - If the cursor is over an item, the row remains in the
hover
state, and the item under the cursor is also highlighted.
Hover styles for different cells
If an entire row is in the disabled state, it shouldn't have a hover state.
TIP
Consider using darker icon colors to increase contrast when using colored cell backgrounds. For instance, switch from --icon-secondary-neutral
to --icon-primary-neutral
.
State | Appearance | Styles |
---|---|---|
Default, hover | ![]() | background-color: var(--table-td-cell); border-bottom: 1px solid var(--border-secondary) . When you hover on, background color changes to background: var(--table-td-cell-hover) . |
Unread, unread hover | ![]() | background-color: var(--table-td-cell-unread) . The hover state is the same as default cell has. |
Selected, selected hover | background-color: var(--table-td-cell-selected) . When you hover on, the background color changes to background-color: var(--table-td-cell-selected-hover) . | |
New, new hover | background-color: var(--table-td-cell-new) . When you hover on, the background color changes to background-color: background-color: var(--table-td-cell-new-hover) . | |
Error, error hover | background-color: var(--table-td-cell-critical) . When you hover on, the background color changes to background-color: var(--table-td-cell-critical-hover) . | |
Warning, warning hover | background-color: var(--table-td-cell-warning) . When you hover on, the background color changes to background-color: var(--table-td-cell-warning-hover) . | |
Current, current hover | ![]() | The row is tagged with tag You . The hover state is the same as the default state. |
Loading | Change opacity of the elements inside a row to --disabled-opacity . Spin has size XS. | |
Limit, limit hover | ![]() | For limiting rows use --overlay-limitation-secondary token. The hover state is the same as the default state has. |
Hover and merged cells
- hovering over a child row highlights the parent cell
- hovering over the parent cell highlights all child rows
Cell coloring
If a cell is colored, it remains colored when you hover over it. Users shouldn't lose information about the cell's color when hovering over a row.
Cell content alignment
Vertical alignment: both table header and body cell content is always aligned to the top.
Horizontall alignment: align cell content both in the header and the body according to the following rules.
Left-aligned
- Text
- Link (URL)
- Keyword
- Code/Numbers/Hashes (text consisting of numbers, symbols, and letters)
- Abbreviation
- Date
- Control element
- Button
- Select
- Tag/Badge
- Icons (if multiple, SERP features)
Center-aligned
- Numbers (if horizontal comparison is needed)
- Icon (if single)
- Particular character
- Image
Right-aligned
- Numbers (if vertical comparison is needed)
- Decimal numbers
- Tags/Badges (when marking the entire row)
Horizontal scroll
The most common case is a scroll bar shown at the bottom of the table. Horizontal scrolling in our tables indicates hidden data beyond the viewport in wide tables. It's needed when:
- All table columns don't fit the viewport.
- Adding a new column from the settings manager makes the table data exceed the viewport.
- The screen where the user views the report is smaller than 992px.
TIP
Having a horizontal scroll in a large table isn't a bad practice; it's a familiar experience for most users (similar to Excel). Avoid making columns too narrow trying to fit them all on the screen, as it can make data less readable.
Two scroll bars
You can add two scroll bars to a table if needed—one in the header and one at the bottom. This is useful when the table is very long and has fixed columns, so users can scroll the table without scrolling to its very end. In these cases, the scroll bars can be in both the header and bottom. Refer to the examples in the Sticky header section.
Pagination
Refer to the Table controls guide for detailed recommendations on pagination.
Table states
For information about table states, refer to the specific document on Table states.