Tables

A table is for data with two dimensions — rows of things and columns of facts about them. These rules cover when a table is the right structure, how to mark it up accessibly, and how to introduce and fill it. One-dimensional collections belong on the lists page.

Lists, not one-column tables

table-005 should GuidesAPI docs

Do not use a table to present a simple one-dimensional list; use a list element instead.

Examples

• ✓ A bulleted list of the regions us-east, eu-west, ap-south
• ✗ A one-column table holding the same three regions

Rationale

A one-column table is just a list with extra structure, so a real list is simpler and more accessible.

Tables for data, not layout

table-010 should GuidesAPI docs

Use HTML elements for their semantic purpose; do not use heading elements, tables, or frames for visual layout.

Examples

• ✓ <img src="pipeline.png" alt="Pipeline stages"> with the explanation as a normal paragraph
• ✗ <table><tr><td><img src="pipeline.png"></td><td>The pipeline has three stages.</td></tr></table>

Rationale

Using tables or headings for visual layout misleads assistive tech about the content’s structure.

Accessible table markup

table-001 should GuidesAPI docs

Format tables accessibly: use proper heading elements, scope attributes, and follow WCAG 2.0 table guidelines.

Examples

• ✓ <th scope="col">Name</th>
• ✗ <td><b>Name</b></td>

Rationale

Proper headers and scope let a screen reader announce which row and column a cell belongs to.

No merged cells

table-006 should GuidesAPI docs

Do not merge table cells (do not use colspan or rowspan).

Examples

• ✓ Two rows that each carry their own us-east cell instead of one merged cell
• ✗ <td rowspan="2">us-east</td>

Rationale

Merged cells confuse screen readers about which header a cell belongs to and break on narrow screens.

Design for narrow screens

table-008 should GuidesAPI docs

Design tables for responsive display: limit column count and keep cell text brief (ideally one line).

Rationale

Wide, wordy tables overflow small screens, so few columns and brief cells keep them readable.

Introduce tables

table-002 should GuidesAPI docs

Introduce tables with a brief description when context helps readers understand or interpret the table. Introductions are optional when the section heading and table structure make the purpose obvious.

Examples

• ✓ The following table describes each field in the response:
• ✗ See below.

Rationale

A short introduction tells the reader how to read the table, and screen readers may not announce a table on their own.

Punctuating the introduction

table-004 should GuidesAPI docs

End the introductory sentence for a table with a colon when it immediately precedes the table, and with a period when other content intervenes.

Examples

• ✓ “The response includes the following fields:” immediately above the table
• ✗ “The response includes the following fields.” immediately above the table

Sentence-case column headings

table-003 should GuidesAPI docs

Use sentence-style capitalization for all table column headings.

Examples

• ✓ Default value
• ✗ Default Value

Explicit empty-cell text

table-007 should GuidesAPI docsMarketingBlog

Use explicit text to mark table cells that have no value, matched to what the empty cell means: ‘Not applicable’, ‘None’, or ‘Unknown’. Don’t use generic symbols such as dashes as empty-cell markers, and don’t leave cells visually blank.

Examples

• ✓ | region | Not applicable |
• ✗ | region | — |

Rationale

A visually empty cell is ambiguous to sighted and screen-reader users alike, and screen readers may announce it inconsistently. Explicit text also distinguishes the different reasons a cell has no value, such as “Not applicable” versus “None”.

Footnote markers

table-009 should GuidesAPI docs

When footnotes are unavoidable in tables, use a defined symbol sequence (asterisk, dagger, double dagger, section, paragraph, number) or consecutive numbering starting at 1.

Examples

• ✓ Footnotes marked *, then †, following the defined sequence
• ✗ Footnotes marked ** and ♦, outside any defined sequence