Table

The Table component should be used for displaying tabular data; it renders an HTML table element.

Usage

When to use

• To display and organize tabular data.
• When comparing, sorting, and filtering multi-dimensional data and objects.

When not to use

• As a layout mechanism.
• As a replacement for a spreadsheet or similar application.

Columns

Sorting

• Sorting is not relevant for all content, so consider when to apply sorting thoughtfully.
• Columns that do contain a sortable data type are interactive and therefore have corresponding hover, active, and focus states.
• A Table may only be sorted by a single value at a time.

Width

Column width is determined by manually resizing the header column and cells within Figma. As a best practice, column width should be adjusted to fit the longest data type within the cell.

Alignment

Use consistent alignment throughout the Table. We recommend using end-alignment in the last column when displaying non-text based content.

Placement

Column placement determines the visual styling based on where the column is placed relative to other columns in the Table.

Rows

Striping

While striping is not required, we recommend it for the added usability benefits.

When using striping in a Table, start with the second row to allow the Table Header to be further differentiated from the the row directly beneath it.

Benefits of striping

• Striping makes data within the Table easier to read by increasing differentiation between rows.
• Striping increases ability to scan, especially for large datasets that result in many rows.
• Striping increases legibility when the type of data is similar between columns; e.g., columns that catalog mostly text or numerical data benefit from more differentiation between rows.

Placement

Row placement determines the visual styling based on where the row is placed relative to other rows within the Table. Only cells with a column placement that is either start or end utilize the row placement property; column position middle does not utilize this property.

Headers

Content

• Headers should be clear, concise, and straightforward.
• The headers should infer clearly what type (string, number, status, etc) of content is contained within the cell.
• Headers should use sentence-case capitalization, not all-caps.

Cells

Density

• We recommend using medium cell density by default.
• If content is complex or a smaller data set (e.g., a Table of basic user data), tall cell density allows for more breathing room surrounding the content.
• If content is largely string/text-based, short allows for more content to be displayed within the page.
• While denser content allows for more rows to be displayed within a single page, it also makes comprehension and scanning more difficult.

Content

While we are not prescriptive about what goes into a cell, there are some best practices to consider:

• We recommended keeping data within a column to one data type. Using more than one data type makes sorting almost impossible.
• While it‘s possible to change the text style/color within a cell, we recommended only using Helios font styles.

Icon usage

Icons nested within cells can help differentiate content, see status, and increase the hierarchy of a piece of data or object. Use the outlined icon style by default and if contrast against other icons is important, use the filled style.

Icons should rarely be used without a text label. A label helps reinforce the purpose and communication of the icon and can reduce ambiguity when expressing complex data.

Leading vs. trailing icons

Both leading and trailing icons increase the visual weight of the content within the cell, so use icons intentionally throughout Tables. Take care not to mix and match different icon positions in the same column.

In general, we recommend using leading icons because the text following the icon will remain aligned and thus be easier for the user to scan.

This component takes advantage of the sort-by helper provided in ember-composable-helpers. While some of the examples provided on our documentation use some of the other helpers provided in this addon, they are not required to use Helios. Read the configuration information provided by the addon if you wish to customize which helpers are included in your own app.

How to use this component

Static Table (non-sortable)

If you don’t have or want to use a model, a basic invocation could look like:

<!-- app/templates/components/table.hbs -->

<Hds::Table>
  <:head as |H|>
    <H.Tr>
      <H.Th>Artist</H.Th>
      <H.Th>Album</H.Th>
      <H.Th>Release Year</H.Th>
    </H.Tr>
  </:head>
  <:body as |B|>
    <B.Tr>
      <B.Td>Custom Cell Content</B.Td>
      <B.Td>{{t 'translated-cell-content-string'}}</B.Td>
      <B.Td>Some other custom cell content</B.Td>
    </B.Tr>
  </:body>
</Hds::Table>

Simple Table with model defined (non-sortable)

To use a table with a model, define the data model and insert your own content into the :head and :body blocks.

<!-- app/templates/components/table.hbs -->

<Hds::Table @model={{this.model}}>
  <:head as |H|>
    <H.Tr>
      <H.Th>Artist</H.Th>
      <H.Th>Album</H.Th>
      <H.Th>Release Year</H.Th>
    </H.Tr>
  </:head>
  <:body as |B|>
    <B.Tr>
      <B.Td>{{B.data.artist}}</B.Td>
      <B.Td>{{B.data.album}}</B.Td>
      <B.Td>{{B.data.year}}</B.Td>
    </B.Tr>
  </:body>
</Hds::Table>

For documentation purposes, we‘ve imitated fetching data from an API and are working with that as our data model.

import Route from '@ember/routing/route';

export default class ComponentsTableRoute extends Route {
  async model() {
    let response = await fetch('/api/folk.json');
    let { data } = await response.json();

    return data.map((model) => {
      let { attributes } = model;
      return { ...attributes };
    });
  }
}

Sortable Table

For the sortable table, the invocation and use is a little bit different:

1. Shape the data model for use; we’ve placed it in the page‘s route.

   • In this example, we’re identifying the column headers (keys) and also capitalizing them.

   • Each column object has two pieces:

     • a key-- used for the model, the sortingKeys, and sortBy
     • a label-- used in the table header cells

// app/routes/components/table.js

import Route from '@ember/routing/route';
import { capitalize } from '@ember/string';

export default class ComponentsTableRoute extends Route {
  async model() {
    let response = await fetch('/api/folk.json');
    let { data } = await response.json();

    // make sure the variable is declared outside of the loop
    // so we can return it in the model response
    let columns;
    let dataResponse = data.map((model) => {
      let { id, attributes } = model;
      columns = Object.keys(attributes);
      return { id, ...attributes };
    });
    columns = columns.map((column) => {
      return { key: column, label: capitalize(column) };
    });
    return { data: dataResponse, columns };
  }
}

2. Invoke Hds::Table in your template file.

<!-- app/templates/components/table.hbs -->

<Hds::Table
  @model={{this.model.data}}
  @columns={{this.model.columns}}
>
  <:body as |B|>
    <B.Tr>
      <B.Td>{{B.data.artist}}</B.Td>
      <B.Td>{{B.data.album}}</B.Td>
      <B.Td>{{B.data.year}}</B.Td>
    </B.Tr>
  </:body>
</Hds::Table>

Indicate which columns are sortable

If you want, you can indicate that only specific columns should be sortable.

<!-- app/templates/components/table.hbs -->

<Hds::Table
  @model={{this.model.data}}
  @columns={{this.model.columns}}
  @sortingKeys={{array 'artist' 'album'}}
>
  <:body as |B|>
    <B.Tr>
      <B.Td>{{B.data.artist}}</B.Td>
      <B.Td>{{B.data.album}}</B.Td>
      <B.Td>{{B.data.year}}</B.Td>
    </B.Tr>
  </:body>
</Hds::Table>

Pre-sorting columns

You can also indicate that a specific column should be pre-sorted.

<!-- app/templates/components/table.hbs -->

<Hds::Table
  @model={{this.model.data}}
  @columns={{this.model.columns}}
  @sortingKeys={{array 'artist' 'album'}}
  @sortBy='artist'
>
  <:body as |B|>
    <B.Tr>
      <B.Td>{{B.data.artist}}</B.Td>
      <B.Td>{{B.data.album}}</B.Td>
      <B.Td>{{B.data.year}}</B.Td>
    </B.Tr>
  </:body>
</Hds::Table>

Pre-sorting direction

You can also indicate that a specific column should be pre-sorted in a specific direction.

<!-- app/templates/components/table.hbs -->

<Hds::Table
  @model={{this.model.data}}
  @columns={{this.model.columns}}
  @sortingKeys={{array 'artist' 'album'}}
  @sortBy='artist'
  @sortOrder='desc'
>
  <:body as |B|>
    <B.Tr>
      <B.Td>{{B.data.artist}}</B.Td>
      <B.Td>{{B.data.album}}</B.Td>
      <B.Td>{{B.data.year}}</B.Td>
    </B.Tr>
  </:body>
</Hds::Table>

Complex sortable Table

Here’s a table implementation that uses an array hash with localized strings for the column headers, indicates which columns should be sortable, and adds an overflow menu.

<!-- app/templates/components/table.hbs -->

<Hds::Table
  @model={{this.model.data}}
  @columns={{array
      (hash key='artist' label=(t 'components.table.headers.artist'))
      (hash key='album' label=(t 'components.table.headers.album'))
      (hash key='year' label=(t 'components.table.headers.year'))
      (hash key='other' label=(t 'global.titles.other'))
    }}
  @sortingKeys={{array 'artist' 'album' 'year'}}
>
  <:body as |B|>
    <B.Tr>
      <B.Td>{{B.data.artist}}</B.Td>
      <B.Td>{{B.data.album}}</B.Td>
      <B.Td>{{B.data.year}}</B.Td>
      <B.Td>
          <Hds::Dropdown as |dd|>
            <dd.ToggleIcon
              @icon='more-horizontal'
              @text='Overflow Options'
              @hasChevron={{false}}
              @size='small'
            />
            <dd.Interactive @route='components.table' @text='Create' />
            <dd.Interactive @route='components.table' @text='Read' />
            <dd.Interactive @route='components.table' @text='Update' />
            <dd.Separator />
            <dd.Interactive
              @route='components.table'
              @text='Delete'
              @color='critical'
              @icon='trash'
            />
          </Hds::Dropdown>
        </B.Td>
    </B.Tr>
  </:body>
</Hds::Table>

Component API

The Table component itself is where most of the options will be applied. However, the child components can also be used if a custom implementation is needed.

• The Hds::Table::Tr component is a template-only component. It supports use of ...attributes but is not eligible to receive interactions (e.g., it cannot have an onClick event handler attached directly to it). It can contain Hds::Table::Th or Hds::Table::Td components.
• The Hds::Table::Th component is a template-only component. It supports use of ...attributes and can contain interactive elements but is not eligible to receive interactions itself. It‘s unlikely you‘ll need to add interactive elements, as sorting is already provided.
• The Hds::Table::Td component is a template-only component. It supports use of ...attributes and can contain interactive elements (e.g., <td><a href="user-info.html">User info</a></td>) but is not eligible to receive interactions itself (e.g., it cannot have an onClick event handler attached directly to it).

Anatomy

Table headers

Table cells

States

Header columns

Only sortable header columns have state variants. Non-sortable header columns are not interactive and therefore do not have interactive states.

Conformance rating

When used as recommended, there should not be any WCAG conformance issues with this component.

Focus in Tables

• Focus will only move through sortable headers and will skip over non-sortable headers as they aren't interactive.
• Interactive elements within cells will receive focus, but entire cells and entire rows will not.

Best practices

Tooltips in headers

Since columns within the table header can control sorting within the table, the header column is not eligible to receive additional interactive elements such as tooltip/toggletip or other components that rely on interactivity to display content (nested interactive elements).

If you need a tooltip, there may not be enough contextual information about the table or the label within the header may not be clear enough.

Interactive rows

The table row element (tr) is not eligible to receive interactions. That is, actions cannot be attached to a table row. If an interactive element is desired, place it within a table cell element (td) within that row (i.e., <td><a href="somelink.html">Some link</a></td>).

For engineers

When providing additional or alternative styles to the table element, do not change the display property in the CSS. This alters how the table is presented to the user with assistive technology; they will no longer be presented with a table.

Applicable WCAG Success Criteria

This section is for reference only. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.