In many contexts, tables are the best way to represent sets of related pieces of data. However, in some contexts, other approaches are better choices.
List or table?
Tables and lists are both ways to present a set of similarly structured items; sometimes it's not obvious when to choose one presentation over the other. To decide which presentation to use, consult the following table:
Item type | Example | How to present |
---|---|---|
Each item is a single unit. | A list of programming language names, or a list of steps to follow. | Use a numbered list, lettered list, or bulleted list. |
Each item is a pair of pieces of related data. | A list of term/definition pairs. | Use a description list (or, in some contexts, a table). |
Each item is three or more pieces of related data. | A set of parameters, where each parameter has a name, a data type, and a description. | Use a table. |
Places not to use tables
- Don't use tables to lay out a page; use your site's standard CSS instead.
- Usually if you have only one row of material, a table isn't the best choice for how to present it. But in some contexts (especially for consistency of layout in reference documentation), it might be.
- If you have only one column in your table, turn the table into a list.
- Don't use tables to lay out code snippets.
- Don't use tables to lay out long one-dimensional lists in multiple columns. For example, if you have a long list of function names, don't try to save space by splitting the list in half and presenting the two halves as a two-column table. Use tables only to present two-dimensional data—that is, material that semantically makes sense to display in rows and columns.
- Avoid tables in the middle of a numbered procedure.
Multi-paragraph table cells
Any table cell can contain more than one paragraph.
To create multiple paragraphs, use the p
element rather
than using the br
element. (The HTML specification
describes which uses of the br
element are legitimate and which aren't.)
Example of a table with some cells that contain more than one paragraph:
Attribute name | Type | Description |
---|---|---|
href |
HTML | Defines the URL for a link. For example, go to the
|
src |
HTML | Defines the path of the image to be displayed. For example, |
Introductory sentences for tables
Introduce tables with a complete sentence that describes the purpose of the table because not all screen readers preannounce tables. The introductory sentence can end with a colon or a period; usually a colon if it immediately precedes the table, and usually a period if there's more material (such as a note paragraph) between the introduction and the table.
Recommended: Change the environment variables to values for your deployment, as listed in the following table:
For more information, see the Tables section of the "Accessibility" page.
Table placement
- When introducing a table, use a complete sentence and try to refer to the table's position, using a phrase like the following table or the preceding table.
- Don't put a table in the middle of a sentence.
- Avoid using footnotes when possible. If your table does refer to footnotes, place them immediately following the table. For more information, see Footnotes.
Table formatting
- Don't add styling to the table element.
- Don't apply a visual style such as a different font, font color, or background color to convey a
header row or column by itself. Use the
th
element to semantically mark up headers in tables. - Don't merge cells. Don't use
colspan
orrowspan
attributes. - Sort rows in a logical order, or alphabetically if there is no logical order.
- If the table is long or complicated—for example, with multiple header rows or columns—consider splitting it into multiple tables.
- Don't present new information in tables through images or symbols alone; always provide a
descriptive
alt
attribute for the image or symbol. For more information, see Alt text.
Table column heads
- Use sentence case.
- Write concise headings and omit articles (a, an, the).
- Don't end with punctuation, including a period, an ellipsis, or a colon.
- Use table headings for the first column and the first row only. Use the
th
element. - Include the
scope
attribute as appropriate for accessibility.
Responsive tables
Where possible, use table CSS that adapts to different viewport sizes.
Link to tables
Where possible, avoid linking to tables; instead, refer to them by table number.