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.|
More places not to use tables
Some other contexts where it's generally best to avoid 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 docs), it may be.
- If you have only one column in your table, turn the table into a list.
- 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.
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
are legitimate and which aren't.)
Example of a table with some cells that contain more than one paragraph:
Used as a placeholder.
Usually the first placeholder in a series.
Used as a placeholder.
Usually the second placeholder in a series.
Some notes on where to place tables:
- 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.
- If your table refers to footnotes, place them immediately following the table.
Don't add styling to the table element.
Table column heads
When composing column heads, follow these guidelines:
- Use sentence case.
- Write concise headings and omit articles ("a," "an," "the").
- Don't end with a period or an ellipsis.
- Include the
scopeattribute as appropriate, for accessibility.
Where possible, use table CSS that adapts to different viewport sizes.