Tables

Use consistent and accessible table formatting to help users identify the information they need. Use tables to display data with a logical relationship, such as comparisons, summaries, values, or reference information. Avoid using tables for page layout or formatting.

tip

For instructions on implementing this guidance with Markdown, refer to Confluence: Formatting documentation.

Each column of a table must have a descriptive name, given in bold in the top row of that column.

Use the same standards for formatting as the rest of the documentation.

If your table describes the various properties of a module or list of features in a screenshot, then list all the relevant properties in the same order as they appear in the screenshot.

UI reference tables

Each UI reference page has one or more tables that document the functions in the UI and their behavior.

For guidance on UI reference pages and the types of information to include in the table, refer to UI reference pages.

For guidance on structuring UI reference tables in Markdown, refer to the Tables section of User manual formatting.

Best practices for accessible tables

Follow these best practices to ensure that the information in tables is perceivable and understandable to all users, including those who use screen readers.

1. Summarize key information in text.
2. Keep tables simple.
3. Use clear header rows.
4. Avoid merged or split cells.
5. Avoid using punctuation to denote empty cells.
6. Separate data into individual cells.
7. Use proper formatting for lists within tables.
8. Provide alternative text for images in tables.
9. Avoid footnotes.

For more information about accessible table formatting, refer to Tables with one header (WAI).

Summarize key information in text

Include a summary of the table's purpose and key highlights in the content surrounding the table, such as in the introduction to the table. For example, "The following table compares product functionality between Unity versions."

This information is critical to help users understand the purpose of a table, especially in the absence of table captions or titles. Don't place a table immediately following a heading. Instead, first introduce the table in the body text.

Keep tables simple

Simple tables are easier to understand and navigate for those using assistive tools, like screen readers. Use a simple table with a single row of headings for the columns. Data in this table format is descriptive on its own and unambiguous.

Break down long or complex tables into smaller, more manageable sections for better usability. For very long tables, consider breaking up the content into multiple pages or headed sections. For example, instead of one nested table with multiple levels, create two smaller tables that are each labeled clearly. Make sure to introduce each table with a textual description.

Use clear header rows

Header cells contain information that is critical to understanding the raw data in a table. Header cells must describe the purpose of the column and can't be left blank.

Use a clear and descriptive header row to make it easier for screen readers to navigate the table. Screen readers announce the corresponding header before reading the content, which helps screen reader users make sense of the data. Header cells must describe the

To mark the first row as a header, use the correct formatting for your tooling in either HTML or Markdown.

HTML headers

In HTML, use <th> for header rows. For example:

<table>
  <tr>
    <th>Header 1</th>
    <th>Header 2</th>
    <th>Header 3</th>
  </tr>
  <tr>
    <td>Cell 1</td>
    <td>Cell 2</td>
    <td>Cell 3</td>
  </tr>
</table>

note

The <thead>, <tbody>, and <tfoot> HTML elements don't contribute to accessibility for screen reader users. If you use these elements for styling or layout enhancements, then you still need to use the <th> element to clearly mark the table headers.

Markdown headers

In other markup languages like Markdown, properly formatted tables automatically add the element for the column headers when they are converted to HTML. For example:

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

note

Bold text formatting for headers should be automatically added by CSS. If your documentation tooling doesn't automatically add bold formatting, then you can add it by wrapping the header text in **. For example, **<Header>**.

Avoid merged or split cells

Avoid split cells, merged cells, and nested tables. When screen readers encounter nested tables or cells that span columns or rows, they can lose count of their position and provide inaccurate information. To maintain a clear relationship between header and data cells, ensure that all cells fit into a logical grid structure.

Instead of merging cells or nesting tables, consider the overall information structure. Sometimes, you might need to break the information into multiple different tables, or repeat some information in some cells.

Avoid using punctuation to denote empty cells

If a data cell in a table has no value, then you can do one of the following depending on the context:

• Enter a numerical value of 0.
• Use a word like N/A or Not available.
• Leave the cell empty.

Do not use punctuation such as - to denote that a cell has no value. Many screen reader users set punctuation to not be read.

important

Only data cells can be left empty. Header cells can't be empty because they describe the purpose of the column.

Separate data into individual cells

Make sure that each separate piece of data has its own cell.

Don't use line breaks (<br> elements) to simulate table rows or lists. When text is resized, the data in the pseudo-rows might not align correctly. Instead, use separate cells or properly formatted lists within tables.

For numerical values, don't use headers in one column and all data in a second column. Screen readers can't determine the relationships between data across columns.

Incorrect example of combined data cells

Shirt color	Sizes and amount in stock
Red	S: 6; M: 13; XL: 10
Blue	M: 5; L: 10; XL: 13; XXL: 1

Correct example of individual data cells

Shirt size	Red stock	Blue stock
S	6	0
M	13	5
L	0	10
XL	10	13
XXL	0	1

Use proper formatting for lists within tables

In the core Engine and package documentation authoring platforms, use the following HTML formatting guidance to create lists inside table cells. In the new documentation platform (formerly known as Hexadocs), use the table component to create tables with lists inside cells.

To create lists inside a table, use the following HTML list elements:

• <ul> for unordered lists (bullet points)
• <ol> for ordered lists (numbered lists)

Using the proper HTML elements creates lists with the same styling as regular lists outside of tables.

List type	Output	Input
Unordered	List item 1 List item 2	<ul> <li>List item 1 </li> <li>List item 2 </li> </ul>
Ordered	List item 1 List item 2	<ol> <li>List item 1 </li> <li>List item 2 </li> </ol>

Manually creating list formatting using symbols and line breaks is bad for accessibility. Screen readers can't parse this text as a list. Instead, the items are read out as separate, unrelated paragraphs.

Provide alternative text for images in tables

If a table contains images or icons, then include equivalent descriptions. Equivalent descriptions such as alternative text allow screen reader users to understand the visual information being displayed.

To describe images or icons when the visual content isn't described in nearby text, use the following alt attributes:

• In HTML, use alt="". For example, <img src="shadows.png" alt="Scene with objects casting shadows">.
• In Markdown, use ![]. For example, ![Scene with objects casting shadows](/path/to/shadows.jpg).
• If the documentation platform doesn't support alternative text, then provide a summary in an adjacent cell or explain the visual content in surrounding text.

note

Avoid using tables for layout purposes to arrange large images.

Avoid footnotes

Adding footnotes to table entries is not supported. If you need to add more context to a table entry, add the information within the cell itself. If the information applies to several items, clarify the point in the text before or after the table.

Don't add footnotes manually. For example, don't add an asterisk to content in a table cell, then start the paragraph that immediately follows the table with an asterisk to add additional context. Adding footnotes manually is a problem for accessibility because screen readers and other aids don't detect the relationship between the asterisks.