Use list elements for grouping content

Applicable Role(s): Content Creator, Developer

Overview

Information that is grouped together visually should also be communicated semantically. This means informing the user a list exists, what kind of list it is, and how many items are in the list.

Without list markup, the page doesn't convey how the items are related, which doesn't communicate the grouping effectively.

Best Practices

Choose the right list type for the grouped content.

Which type of list you use will depend on whether order is important:

  • Use an ordered/numbered list (<ol>) if re-organizing the list items' meaning would change the meaning of the list (like a sequence of steps).
  • Use an unordered/bulleted list (<ul>) if the list elements relate to each other, but can be re-organized in the structure without losing meaning.

Lists can only contain list items.

This means list tags (<ol>, <ul>) can only contain list item tags (<li>). Elements like <div>, <br>, etc., are not valid and can't be used in list tags. See Use valid markup in webpages.

Accessibility notice on definition lists

While HTML provides a definition list option, its accessibility support is currently spotty as of testing in August 2021 and isn't suggested for widespread use. The definition data and term elements don't communicate the list structure as expected.

To better convey term and definition content, use heading structure or other list types.

Pattern Examples

The following patterns highlight the code needed, but most site editing platforms come with a way to inject lists in the text edit field. Using those buttons should render list markup correctly and easily.

A rich editor toolbar containing text markup options, with list formatting options highlighted

Inaccessible list markup

While the following lists look numbered or bulleted, these examples are actually just paragraphs containing number text or asterisks acting as bullets. This won't tell the user upfront how many items are in the total list, or how many items are in it.

Rendered content

1. This is the first step in a sequence

2. This is the second

3. This is the third

* This looks like a bullet list
* This looks like another bullet item

Code


<p>1. This is the first step in a sequence</p>
<p>2. This is the second</p>
<p>3. This is the third</p>

<p>* This looks like a bullet list<br />
   * This looks like another bullet item</p>
  

Accessible ordered list

Rendered list

  1. This is the first step in a sequence
  2. This is the second
  3. This is the third

Code

  <ol>
    <li>This is the first step in a sequence</li>
    <li>This is the second </li>
    <li>This is the third</li>
  </ol>

Accessible unordered list

Rendered list

  • This is a normal list
  • It has items
  • Nothing too fancy
  • It can have links to other pages

Code

  <ul>
    <li>This is a normal list</li>
    <li>It has items</li>
    <li>Nothing too fancy</li>
    <li>It can have links to other pages</li>
  </ul>