Skip to main contentSkip to search

Table

A table is a specific pattern for comparing datasets in a very direct and analytical way.

installyarn add @clayui/core
version3.123.0

Beta3.123.0View in LexiconCHANGELOGstorybook demos

Usage

The Table component is designed for comprehensive entry comparison, particularly when dealing with text-heavy data. If your data involves images, we recommend using lists or cards instead. Please note that each table entry or row supports a single data type per column to avoid potential comparison and sorting issues.

When utilizing a table with the management toolbar, it is essential to include checkboxes in table entries. This ensures that selections and actions are properly reflected in the management toolbar. Refer to the dataset display examples for further clarification.

Parts

The Table component is composed of the following elements:

  1. Header
  2. Row
  3. Cell

Header

The Table component is composed of the following elements:

  1. Header
  2. Row
  3. Cell

Default column headers are left-aligned and have semi-bold weight. However, there are other cases in which column headers can be center or right-aligned to improve readability and alignment with table content. For example, when using numbers in a table, we recommend aligning the column header and content to the right.

A table header can have these interactive attributes:

Sorting (if available): The column header has an arrow next to it indicating the sort direction: descending Z-A (down arrow) and ascending A-Z (up arrow). The text is underlined on hover state.
Drag & drop (if available): The column header shows a drag icon in the hover state.

A paragraph is a self-contained unit of a discourse in writing dealing with a particular point or idea. Paragraphs are usually an expected part of formal writing, used to organize longer prose.

Row

A Table row represents a horizontal grouping of cells, organizing information across various columns. It typically contains content related to a single item or record, presenting data in a structured format for easy comprehension.

Cell

In a table row, the first cell or Title Cell may contain the following elements:

  1. Handler
  2. Button
  3. Checkbox
  4. Icon
  5. Content

The fifth element can be used in any cell and is not specifically limited to the first. It may take various forms, such as text, an icon, a checkbox, a number, etc.

The fifth element can be used in any cell and is not specifically limited to the first. It may take various forms, such as text, an icon, a checkbox, a number, etc.

Size

The Table component offers three sizes:

  1. Large (Default)
  2. Medium
  3. Small

Large (56px)

Medium (48px)

Small (32px)

Table Sizes with long texts

When text exceeds the column width, the row height should dynamically adapt and apply padding instead of maintaining a fixed height of 56/48/32px. To ensure accessibility, the table component should not truncate text.

Sections

Sections enable easy data grouping in a Table component. Use Section to group entries based on common criteria for efficient and intuitive organization.

Visual States

Row States

Default

You can use the table group separator to group a series of table entries.

Hover

When a user hovers over a table row, quick actions from the actions menu are displayed for the element. A maximum of three actions (represented by icons) can appear.

When the row is selected, the actions do not appear on hover state.

Selected

Row Attributes

Table rows contain the following attributes:

  1. Checkbox
  2. Main column text
  3. Columns
  4. Actions button

Attributes

  • A table entry can have a checkbox, a radio button, or neither of them.
  • You can select a row by using the checkbox or radio button, depending on the selection type in the list. The background is not selectable.
  • You can add links to a row to navigate to other areas.
  • A row can have related actions. If there is only one action for the row that can be represented by an icon, you don't need to use an actions menu. Otherwise, include an actions menu on the right side of the row.
  • Use the main text as an action for the following use cases:
    • A Folder that navigates to the next level
    • A File that navigates to its detailed view
  • Never use the row action to view a preview. This is always a secondary action placed inside the row's action menu.
  • If the link drives the user out of the site, please identify visually that this link will open in a new page.
  • A cell entry can include a button as the main action of a table entry. An example could be "Execute".
  • You can drag and drop selected elements into a folder. A click and drag over a non selected element implies selection.

Hover

Table rows on hover contain the following attributes:

  1. Checkbox
  2. Main column text
  3. Columns
  4. Actions button
  5. Quick actions displayed on row hover

Row Interaction Limitation

Do
Don't

Columns Drag and Drop

Drag and drop is configurable for tables. This lets the user exchange column positions, excluding the first column. Tables that allow drag and drop provide the action in the column's header.

Columns visibility

You can only toggle visibility for columns that work with a management toolbar that implements this feature. All columns can be hidden, except the first one since it is the reference column.

Columns layout

A table can contain one or more columns, and deciding how to place them properly can be cumbersome. We provide a set of guidelines that you can follow to make this decision easier.
While the main column must always be placed on the leftmost side, the remaining columns can be placed in a couple different layouts:

  • 2 columns: Place the second column right next to the first column, while respecting the margins.
  • N # of columns: Place columns equidistant.

Content Format and Alignment

  • Headers must always be left-aligned and semibold.
  • The first column's value must always be semibold.
  • The remaining columns values must be regular font weight.
  • Text values, dates, stickers, labels, and badges must always be left-aligned.
  • Numbers, with or without unit, must be right-aligned.

Example

How can this be improved? Create an issue!