Table

A table contains data arranged in rows and columns. They are used to communicate relationships between content and to display references, comparisons, and choices. Features includes text inputs, text links, and sorting.

Status

Figma UI Kit	PublishedElement can be used in production
Vanilla	PublishedElement can be used in production
Angular	In progressElement design and development in progress
React	In backlogElement is in backlog
Documentation	In progressElement design and development in progress

What's new

Table is a new component for the v2 design system. It incorporates the updated font ramp and color palette, in addition to accessibility enhancements.

Anatomy

The parts of a table, labeled 1 through 6. — The table component contains six elements:

**Body cell**: input field for body text can contain alphanumeric text or links.

**Body text**: content related to its corresponding column header.

**Header cell**: input field for header text is the first row across all columns.

**Sort function (optional)**: displays whether information is set to ascending (up arrow) or descending (down arrow).

**Header text**: title or concise description of the content within its column.

**Action menu trigger**: conveys that the header cell is enabled as a trigger to open a menu. The menu contains features available within the table including sort.

Usage

Comparison

Use a table to help users decide between two or more items. Comparison tables allow users to review multiple factors or characteristics quickly and easily before making a decision.

Kinds

Consider the amount of information or kind of content you wish to present to help determine which table best meets your use case.

Borders

Borders can be used to create grid, horizontal, or freeform tables.

Example of a three-column table in the grid style. — Grid: Recommended for dense tables. The grid style includes both horizontal and vertical borders. The grid style is the default table style.

Example of a two-column table in the horizontal grid style. — **Horizontal borders**: Recommended for most data sets. A table with horizontal borders reduces visual noise and allows users to easily scan data.

Example of a two-column table in the freeform style. — **Freeform**: Recommended for light data sets only. Freeform tables do not include horizontal or vertical borders.

Alternating rows

You can apply a color fill to every other row to increase readability in large data sets. This styling is available for tables with all, horizontal, or no borders.

Sizes

Tables can extend anywhere within the margins of the screen grid. The overall size of the table depends on its location in relation to other elements on the page. When deciding the size of your table, consider the content you wish to display and the layout within your experience.

The following are recommended pixel ranges that fit within their respective breakpoints (see Grid foundations page). However, these pixel ranges are not preconfigured within the component. Additionally, pixel ranges are used to set fixed column widths, which increase as the ranges grow.

Viewport range	Table pixel range	Column width
X-small	288px - 447px	202px
Small	448px - 735px	210px
Medium	720px - 975px	218px
Large	944px - 1285px	226px
X-large and larger	1270px - 1487px	234px

There are no height restrictions for table, and individual row height automatically adjusts to fit its contents.

Density

Table is offered in three different densities. Row height is determined by the selected density, but will increase to accommodate more content when necessary.

Density	Use case
Compact	Use compact size when you have large amounts of information to display. By reducing the space between content, the user can easily scan and compare the information.
Default	This default size can be used in most cases, as long as you can maintain visual balance.
Comfy	Comfy size can be used when there isn’t a large amount of information to display and the whole table can be viewed on screen.

Density does not affect column width. Column width is defined in the table’s configuration, and can be adjusted per column. Speak with your engineering team when creating tables to determine what width works best for the content you’re trying to display. For example, you may want to set columns containing descriptions wider than their surrounding columns. Review table documentation on storybook for more information on how to adjust column width.

Layout

Alignment

Alignment is determined by the information within each column. Column headers should always align to their corresponding content.

Left-align

Left align text and qualitative numbers, including zip or postal codes and phone numbers.

Right-align

Right align quantitative numbers including money, quantities, measures, and percentages unless they are in the first column of the table. Align numbers to their decimal for readability.

Interaction

Behavior and states

Sorting

The sorting feature resides within the action menu. Once the action menu is triggered, sort can be applied in either ascending or descending order. Sort functionality can be enabled on one, multiple, or all columns within the table.

Example of an expanded action menu, where Sort ascending is selected. — An option to unsort the table by the selected column can also be found within the menu.

Sticky header

A sticky header can clarify each column’s context when a table consists of more rows than can be shown within a fixed height, and vertical scroll is required to view the entire dataset.

Pinned columns

You can pin columns to the left of the table when there are more columns that can be shown within a fixed width. Note that columns cannot be pinned in the middle or at the end of the table. However, if there is a column consisting of an overflow action menu, that column is programmatically pinned at the end of the table in the UI.

Image showing a pinned column, which remains on top of the table’s body cells when users scroll. — Enabling a pinned column ensures that it, and all columns that precede it, will remain in view within the defined width of the table as users scroll horizontally. An elevation effect gives pinned columns height over unpinned ones.

Expandable rows

Expandable rows are used to provide additional information that is not visible in the table’s default rest view. Upon selection, the row expands to fill the width of the table and, if necessary, the expanded row’s content can be further accessed by scrolling.

Note that loading data may occur at the moment the row is expanded. In this case, speak with your engineering team about how your table will retrieve and display data. If there is a wait time of three seconds or more, use a small loading indicator as a placeholder to let users know that their content is loading.

Supported content within the expanded section is limited to text in grid or list form.

Action is taken to expand the second row in a table. — Expansion is indicated by a chevron.

Standards

Content

Headers
Headers should be clear, concise, and descriptive. Use sentence case and capitalize the first word for all headers.
Do: Email address
Don’t: Employee’s Email Address

Organization
Organize information according to a hierarchy of important information. Otherwise arrange data in ascending order, descending order, or alphabetically.

Punctuation
In most cases, punctuation is not necessary inside tables, unless writing information in full sentences such as within description and use case columns.

Live demo

This demo lets you interact with the component and view the code. To see other interactive examples of this component or for additional developer documentation, visit Storybook.

You are now entering a live demo of the component.

<div role="table" id="docs-components-table--sort" data-dds="table" class="dds__table"></div>
<script>
const tableElement = document.querySelector("#docs-components-table--sort");
const config = {
    columns:[{"value":"Heading 1","sortBy":"descending"},{"value":"Heading 2"},{"value":"Heading 3"}],
    data:[[{"value":"Row 1"},{"value":"Row 1"},{"value":"Row 1"}],[{"value":"Row 2"},{"value":"Row 2"},{"value":"Row 2"}],[{"value":"Row 3"},{"value":"Row 3"},{"value":"Row 3"}]]
};
const tableAPI = DDS.Table(tableElement, config);
</script>

Copy code

View the table demo and code for Vanilla.

Visit Storybook

Table

Status

Contents

What's new

Anatomy

Contents

Contents

Usage

Comparison

Kinds

Borders

Alternating rows

Sizes

Density

Layout

Alignment

Left-align

Right-align

Interaction

Behavior and states

Sorting

Sticky header

Pinned columns

Expandable rows

Standards

Content

Contents

Contents

Live demo

You are now entering a live demo of the component.

Vanilla

Contents

Table

Status

Contents

What's newCopy link to this section

AnatomyCopy link to this section

Contents

What's new

Anatomy