Preview brand Custom

Table

For comparing several things across the same attributes. If there's only one column of facts, use a list instead.

EngagementLengthEnds with
Prototype Sprint2–3 weeksA tested prototype
Design PartnerFrom one quarterOngoing design capacity
EngagementLengthEnds with
Prototype Sprint2–3 weeksA tested prototype
Design PartnerFrom one quarterOngoing design capacity
Show code
html
<div class="sn-table-wrap">
  <table class="sn-table">
    <thead><tr><th scope="col">Plan</th><th scope="col">Length</th></tr></thead>
    <tbody><tr><td>Prototype Sprint</td><td>2–3 weeks</td></tr></tbody>
  </table>
</div>

When to use it

  • Several things compared across the same attributes.
  • Figures that someone will read across and down.

Use something else when:

  • There is one column of facts: a list.
  • It is a name beside a paragraph: a list of terms, or headings and text.
  • You want things side by side for the look of it: a grid, never a table.

How it works

  • Column headers use <th scope="col">; a first column that names each row can use scope="row".
  • The first column never gets narrower than 14 characters, however long the text beside it, so a name and role such as "Product Designer, Director" wraps at most once or twice, never a word a line. It scrolls sideways before it squeezes.
  • A two-column table with no header row is a list of terms and descriptions. Use a table only when the rows have the same attributes; for a name beside a paragraph, keep the name short and the description to a sentence or two.
  • Rows are separated by hairlines, not stripes, and the table sits in a card with the card radius.
  • Wide tables scroll sideways inside their card on small screens. A scrolling table becomes focusable and labelled, so keyboard users can scroll it too.
  • Numbers use tabular figures so they line up. In print, a table of a dozen rows or fewer is kept on one sheet; a longer one breaks between rows with its headings repeated.
  • A table read a row at a time can stack on a phone (.sn-table--stack): each row a block, each value under its column's name.

Accessibility

What it does for you

  • A real table: column headings are heading cells, so each cell is read with its column’s name.
  • A table too wide for its box scrolls sideways inside it, never the page. It then becomes a region the keyboard can reach and scroll, named "Table, scrolls sideways", with a hint underneath.
  • A table that fits is not a stop for the keyboard.
  • For a table read a row at a time, .sn-table--stack turns each row into a block on a phone, each value under its column’s name.
  • On paper it fits the page’s width, and a long one breaks between rows with its headings repeated.

What you need to do

  • <th scope="col"> for column headings, and scope="row" where the first column names each row.
  • A heading or a sentence before it saying what it shows.
  • Never a table for layout.

Keyboard

KeyWhat it does
TabMoves to a table that scrolls.
Left and RightScroll it.

What a screen reader is told

  • A table, with how many rows and columns. Each cell with its column’s heading.
  • When it scrolls: a region, "Table, scrolls sideways".

This is what the browser reports to assistive technology. What each screen reader then says varies, and has not been listened to yet.

WCAG 2.2

CriterionLevelHow this meets it
1.3.1 Info and RelationshipsAHeading cells are marked as headings for their columns.
1.4.10 ReflowAAA wide table scrolls in its own box; the page doesn’t.
2.1.1 KeyboardAA scrolling table can be reached and scrolled from the keyboard.
4.1.2 Name, Role, ValueAA named region when it scrolls.

The criteria this component has a part in. A page that uses it still has to meet the rest.

Checked

CheckHowResult
Automated (axe-core)WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in darkPassed
Nothing found, light or dark
Narrow screenNo sideways scrolling at 320px wide (WCAG 1.4.10)Passed
No sideways scrolling
Keyboard and what the browser reportsReal key presses on the live example, and the role, name and state given to assistive technologyPassed
5 of 5 checks pass
On paperSomnia’s print check: no overlaps, stranded headings or controls on the pagePassed
No faults on 4 sheets
Screen readerListened to by a person, in VoiceOver and NVDANot yet
Not yet checked by a person

The 5 checks made with the keyboard, on the example at the top of this page:

  • Passed Column headings are heading cells, and the browser reports a table of three columns
  • Passed On a phone a wide table scrolls in its own box, and the page does not
  • Passed It is then a region named "Table, scrolls sideways" that takes the focus, and Right scrolls it
  • Passed A hint under it says it scrolls; the hint is for the eye, the name is for a screen reader
  • Passed A table that fits its box is not a stop for the keyboard

Run by script on against Somnia DS 1.89.0, in Chromium with axe-core 4.14.0. How these checks work, and every component's results.

Not yet checked

  • How it sounds in a screen reader (VoiceOver, NVDA, TalkBack) has not been checked by a person. The roles, names and states the browser reports are checked by script; what is actually spoken is not.
  • Windows high contrast (forced colours) has not been looked at by a person.
  • Every table that scrolls has the same name. On a page with several, a screen reader’s list of regions can’t tell them apart.
  • The stacked form on a phone has not been listened to: its table roles are written into the markup to survive the change of layout.

Evidence

Where it's used

WhereFor
These docsOn most pages.
Articles and legal pagesA Markdown table on any site is wrapped and styled the same way.
Somnia CMSTables written in the editor.

What we saw, and what changed

WhenWhat we sawWhat changed
Tables in articles and legal pages were plain Markdown tables, unlike the docs’ own.One table for every site (1.5.0).
A wide table ran off the side of a phone, with no sign there was more and no way to scroll it from the keyboard.It scrolls in its box as a labelled region the keyboard can reach, with a "Scroll sideways" hint (1.5.0).
Column headings were lighter and smaller than the rows, and read as a caption.Headings are as strong as the rows, on a light band (1.55.0).
A table read a row at a time was hard work on a phone, scrolling sideways for each value..sn-table--stack (1.77.0).
On paper a table of twenty rows moved whole to the next sheet and left most of a page empty.A long table breaks between its rows (1.82.0).

From building and using it on real sites, each entry taken from the changelog or the build's own notes. This is observation by the studio and its clients, not research sessions with users.

What we don't know yet

  • Whether people on phones notice that a table scrolls is not known: the hint is there, and nothing is counted.