Tables

When to use a table

View in Figma

  • Organizing similar objects where each object has the same attributes.
  • To display user generated content (rules, signals, lists etc…).
  • Comparing data across objects.
  • Common attributes aligned in columns are easier to scan and compare.

When to consider something else

  • When you need to display data sets with a blend of text, images, data viz or content with mixed formatting, opt for a different layout using either List or Card.

Definitions

  • Object: This is the hero of your table row (ex. in Lists it's the name of the List).
  • Properties: Object values.
  • Values/data: Individual property or data fields.
  • Row: Horizontal display. All values in a row relate to the corresponding object.
  • Column: Vertical display. All values in a column relate to the corresponding property or data header.

Table Display

Number of columns

6 columns is the max used in a full-width table in the product (Agents). When determining what properties and data to display, prioritize high impact, need-to-know information that’s crucial to scan and sort at the top level. Extra nice-to-know properties and data can surface on the details page for the object. Tables should show as little information as possible while giving the user enough information to confidently take action.

Content order (From left to right):

  • Name/Title (required): This should always be in the first column.
  • Sets of data (required): Display after name/title in order of priority (from left to right).
  • Audit data (optional)
  • Actions (optional)
    • Action buttons should display in the far right column. They should always include text that describes the action (ie. no standalone icons).
    • We most frequently include the 'view' action that takes the user to the details page for the object. Display more actions (edit or delete) on the detail page.

Alignment

Always left-align columns unless the content within the column is a numeric value that is easier to parse when right-aligned (percentages, monetary values, quantities etc…).

Null states (–, 0, N/A)

  • You can use 3 null states in a table:
    • – : Use an em dash as a placeholder for content that doesn’t have data yet but may in the future (ex. when a description is optional).
    • 0 : Use zeros for live numeric content.
    • N/A : Do not use in the product.

Data points per row

  • One data point
    • Most tables should have one data point per cell. One line tables are easier to read and scan than denser tables. Also, sorting by column makes more sense when each cell contains one item.
  • Two data points
    • You may need to include a second data point to provide supporting information. This is ok, but understand that the columns are sortable solely by the first line of data. If you need to sort by the second data point, either consider a different table structure or try using a filter.

Table Controls

Sorting

By default, we sort tables to surface the most recent object created or event that occurred. When in doubt, default to sorting your table by descending dates.

Pagination

Most tables should use pagination. When in doubt, paginate.

  • The default threshold to paginate is after 20 results.
    • If possible, refer to analytics to measure and determine the best pagination default for a given collection.
    • Rare case: If you have a table that will always have fewer than 20 rows, you may opt not to paginate. (Ex. API keys table).
  • Pagination should update the page URL so users can share links to the correct page and use browser back/forward buttons to navigate through pagination history.