Best practices for implementing and HTML lists

HTML lists are a fundamental element of HTML semantics. When implemented correctly, they allow assistive technologies to effectively convey how related content is organized, by announcing that items are grouped in a list, the number of items present, and the position of each item in the list.

Conversely, poor use of the ‎⁠<ul>⁠, ‎⁠<ol>⁠ and ‎⁠<li>⁠ tags can harm the user experience of people browsing with a screen reader, and lead to non‑compliance with accessibility standards such as WCAG, or French references like RGAA and RAWeb.

This article presents several essential rules for implementing HTML lists in a way that is both semantically correct and accessible.

1. Avoid single‑item lists

By definition, a list represents a set of elements that share the same nature or participate in the same logical structure.

Examples :

1. Lists of steps in a process
2. Pagination pages list
3. People in a group
4. Links in a menu
5. Videos in a category

Using a ‎⁠<ul>⁠ or ‎⁠<ol>⁠ tag to wrap a single element is generally discouraged, because it is inconsistent with the very definition of a list.

Example of implementation to avoid

<ul>
<li>Terms of use</li>
</ul>

In this situation, using a simple paragraph or another structuring element is often more appropriate.

Tolerated cases

This type of implementation is tolerated for certain reusable components that usually display several items, but may occasionally show only one (results list, gallery, product cards, etc.).

In that context, keeping the list structure remains relevant, as it preserves component consistency and avoids complex conditional logic in the code or the creation of another component.

2. Know when to use ‎⁠<ul>⁠ and ‎⁠<ol>⁠

The choice between an ordered list (‎⁠<ol>⁠) and an unordered list (‎⁠<ul>⁠) should be guided by the logical relationship between the items.

The ordered list ‎⁠<ol>⁠

An ordered list is appropriate when the order of the items has intrinsic meaning.

Example use cases

• Successive steps in a process
• Installation procedure
• Rankings
• Timeline

Example of good implementation

<ol>
<li>Create an account</li>
<li>Validate your email address</li>
<li>Log in</li>
</ol>

The unordered list ‎⁠<ul>⁠

An unordered list is appropriate when items are simply grouped, without any notion of sequence or order being necessary for understanding.

Example use cases

• Features
• Benefits
• Categories
• Related links

Example of good implementation

<ul>
<li>Keyboard accessible</li>
<li>Screen‑reader compatible</li>
<li>Responsive</li>
</ul>

Special case: ordered list items already numbered

Sometimes, the textual content of items in an ordered list is itself numbered. If this numbering is an integral part of the visible content and is also announced by screen readers, using a ‎⁠<ul>⁠ list is acceptable.

WCAG and RGAA do not require the systematic use of an ‎⁠<ol>⁠ tag as soon as an order is indicated in another way and is conveyed equally well visually and by screen readers. The important thing is that the logical relationship between the items is properly conveyed to all users.

3. Respect the HTML structure of lists

A common error is to insert elements other than ‎⁠<li>⁠ directly inside a ‎⁠<ul>⁠ or ‎⁠<ol>⁠ container, such as ‎⁠<div>⁠, ‎⁠<p>⁠, ‎⁠<hn>⁠, etc.

Example of non‑accessible implementation

<ul>
<div>Item 1</div>
<div>Item 2</div>
</ul>

Or:

<ul>
<p>Description</p>
<li>First item</li>
</ul>

To be accessible, an HTML ‎⁠<ul>⁠ or ‎⁠<ol>⁠ list must only contain ‎⁠<li>⁠ items as direct descendants.

Example of accessible implementation

<ul>
<li>Item 1</li>
<li>Item 2</li>
</ul>

If additional content needs to be associated with an item, it must be included inside the corresponding ‎⁠<li>⁠.

Example of accessible implementation:

<ul>
<li>

<h3>Title 1</h3>
<p>Description of item 1</p>
</li>
<li>
<h3>Title 2</h3>
<p>Description of item 2</p>
</li>
</ul>

This rule guarantees consistent output for screen readers, which rely on this structure.

4. Do not include the list title as an ‎⁠<li>⁠ item

Another common mistake is to treat the list title as the first list item.

Example of implementation to avoid

<ul>
<li>Services offered:</li>
<li>Accessibility audit</li>
<li>Training</li>
<li>Support</li>
</ul>

In this example, the screen reader will announce four items, even though only three of them are actually the content of the list.

Good practice

The title must be implemented outside the list.

Solution 1

Use a heading tag ‎⁠<hn>⁠ appropriate for the page’s heading hierarchy.

Example:

<h2>Services offered</h2>
<ul>
<li>Accessibility audit</li>
<li>Training</li>
<li>Support</li>
</ul>

Solution 2

You can also associate the title with its list using the aria-labelledby + id attributes, where the id value is unique in the HTML document.

Example:

<h2 id="services-title">Services offered</h2>
<ul aria-labelledby="services-title">
<li>Accessibility audit</li>
<li>Training</li>
<li>Support</li>
</ul>

To go further

We love talking about accessibility! Want to discuss your project?