Table

Tables display tabular data in a basic grid composed of cells, columns, and rows. This format makes it easy for users to scan and compare large amounts of data.

Examples

base-table-table--default
Loading story...
TODO:
Add column sorting example. Create an issue
TODO:
Add pagination example. Create an issue
TODO:
Add responsive table examples. Create an issue

View design in Pajamas UI Kit →

Structure

Numbered diagram of a table structure
  1. Caption: Provides a meaningful description for a table. A caption should only be optional when a heading directly precedes the table and provides clear enough context for it.
  2. Header cell: Can be used to sort table content.
  3. Icon: Indicates sort direction:
  4. Body cell: Supports text, buttons, links, and text accompanied by other common elements like an avatar or icon.

Guidelines

When to use

  • Display tabular data for comparison.
  • Display structured content, where each entry has the same attributes.
  • Let users review, enter, edit, or filter granular data sets.
  • Display a data set that will continue to grow (e.g. Issues, Environments, and User Profile pages).

When not to use

  • Create page layout or design structure.
  • Display a list of continuous, vertical indexes of text or images. Use a semantic HTML list instead.
  • Display contained content and actions on a single topic. Use Cards instead.
  • For hierarchical structures. Use the Tree view instead.

Variants

  • Basic: A basic table is the default option for this component, however, additional functionality can be added to enhance the table for different use cases.
  • Striped: A striped table adds zebra-striping to the entire table, starting with the the header row. The alternating row background colors can be helpful to differentiate row content.
  • Condensed: A condensed table cuts the body cell padding in half. Use a condensed table when the content presented is data heavy and text only. For example, displaying log files.

Appearance

  • Tables work across multiple screen sizes and conform to responsive guidelines.
  • Tables take up the full width of their container element. However, it is important to note that wide tables make it difficult to read and scan small amounts of content, because the data is widely separated. For legibility, ensure content is laid out and aligned properly.
  • Don’t simply shrink an entire table to fit the viewport or apply a fixed width to a table to the point that it compromises legibility. The same way stretching tables 100% to the width of the viewport is not recommended, a small, shrunken table view can create a cluttered interface. Use a responsive table view instead.
  • Order the table content by importance, based on the information needs of your users.
  • Text in tables tends to end up in narrow columns. Left-align text content, rather than justifying or centering it, to avoid confusion or readability issues.
  • The Label text styles from the UI type scale are used for product tables since the content is more data rich and requires less line height.
  • The Paragraph text styles from the Documentation Markdown and Compact Markdown type scales are used for markdown tables in GitLab issues, merge requests, and documentation.
  • In some circumstances, right-aligning the text content helps with readability. For example, right-align the numeric data with a consistent number of decimal places to improve scannability.
  • Tables may switch their alignment for right-to-left audiences when designing for internationalization.
  • Use white space in tables to improve scannability, visually separating data elements so that each can be individually identified and read as separate from the others.
  • To help with styling, use horizontal lines between rows to visually separate content, including the last row item. Avoid any border or frame surrounding the table. Do not style tables to look like nets, with every number enclosed.
  • Do not apply vertical lines between columns. In general, tables without vertical lines look better and are easier to scan and read.
  • By default, row content is vertically top aligned. However, in some cases it does makes sense to vertically center align content. Use your best judgement on when this is an exception.
  • As general rule, consider that alignment within a table is more important than consistency from table to table.
DoDon’t
A table row example with multiple lines that wrap with a green line highlighting the top alignment
Top align in most cases
An incorrect table row example with a single line with a red line highlighting the middle alignment
Avoid middle align

Behavior

Search & filter

  • Any filtering controls that manipulate the data set should be placed directly above the table with the option to clear all data. See filter guidelines.

New row

  • When a new row is dynamically added by the system, the background color of the row should be set to $green-50 in order to highlight the addition.

Ordering & sorting

  • Sorting is designed as a native functionality of tables. Tables use column sorting rather than list sorting.
  • The default sort direction of a table is usually ordered by one specific column attribute, such as status, last updated, or priority. Sorting is indicated in the table header using the arrow down and arrow up icons.
  • Clicking the icon will sort the rows based on the selected column, in ascending order first, and subsequently toggling between ascending and descending order.
  • Sorting can be disabled to prevent users from changing the sorting order of a column. The default order will utilize one specific attribute.
  • The sorting icon and functionality should not be visible on responsive tables.
  • To enable sorting for a particular table column, add sortable as a property in your fields data, like so:
fields: [
    {
      key: 'first_name',
      label: 'First name',
      sortable: true,
    },
    ...
]

Pagination

  • Tables displaying data sets with more than 20 items should use pagination. See pagination guidelines
  • If a condensed table is used, data sets with more than 40 items should use pagination.

Additional actions

  • A table row can include additional actions in the far-right column.
  • These actions should be visible at all times rather than showing on-hover.
  • If there are two or more actions in a table row, consider using a button group or a “more menu” button with a dropdown list option.

Responsiveness

At smaller breakpoints, tables can either maintain a tabular layout and scroll horizontally to view the overflow without breaking the page layout, or each row can be transformed into its own group where header content is present within each group.

  • If the data in each row needs to be compared to data in other rows then maintain the tabular layout.
  • If the content simply shares headers and can live on its own without comparison, transform each row into its own group.
  • If a row has embedded actions that could be missed when overflowing in the default tabular layout, transform each row into its own group so the actions can always be visible.

Interactive tables

If table cells needs to be navigable (not just some of the content within), consider extending the table as a grid composite widget.

Selecting rows

TODO:
Add behavior guidelines for selectable rows. Create an issue

Content

Caption

  • A <caption> provides a meaningful description for a table.
  • A table header is the row at the top of the table that helps identify the columns below. The header provides clarity if data is non-descriptive or ambiguous.
  • Tables should always include table headers. For short tables and for tables whose data are self explanatory, column headers are sufficient. For long tables or tables where data may be confusing, it is best to include row and column headers.
  • Headers should be short, descriptive, and relevant. Avoid headers that are too long for the content in the rows below, and use title-case.

Columns

  • Columns should be ordered by priority or in a way that tells a story with the data. Size columns according to the data they contain rather than making them all an even width. For example, columns of small content should be narrow, while columns of paragraphs should be relatively wide. Allow the browser to lay out the tables according to the viewport size.

Rows

  • Rows can have a mix of read-only and editable cells with content populated by users. See additional actions on table rows.

Empty state

Null values

Representing null values should be made on a case-by-case basis. Some ways of addressing this are:

  • Keep the cell empty. For example, if no data is returned.
  • Use text to indicate what is missing. For example, "Unassigned" if there is no assignee.
  • Use a dash ("-"). For example, if there is no data and a text explanation is not applicable.

Truncation

  • Truncate long text strings with an ellipsis (“…”). On hover, the truncated text should display a tooltip including the full text. See tooltip guidelines

Accessibility

Use proper semantic markup, so that users of screen readers can navigate through the table one cell at a time, hearing column and row headers spoken to them.

  • <th> should not contain heading elements.
  • <th> should be descriptive and relevant.
  • <th> should have a defined scope attribute to establish relationships between the table headings and rows/columns; for example, <th scope="col">.
  • <caption> must be used to provide a title for a table.
  • <caption> must be an immediate child element of <table>.

Reference

Last updated at: