Make a list accessible

Understand the key considerations for making a list accessible.

A list can benefit from having certain properties programmatically exposed so that users who rely on assistive technologies know that it’s a list and, optionally, what it’s called.

Programmatically exposing content means assigning certain markup to it so that software or machines can reliably interpret what it is.

To learn about why it’s important to programmatically expose certain information about user interface elements, see the Knowledge Areas:

Meeting the Web Accessibility Standard

When a list's structure is conveyed through presentation and can also be determined programmatically, this meets WCAG 2 Success Criterion 1.3.1 Info and Relationships (Level A).

Accessible name

If a list has an accessible name, a screen reader will announce that name when the user navigates to the list.

By default, lists do not have an accessible name, and they are not required to have one. But an accessible name on a list can sometimes help screen reader users better understand the list’s contents or purpose.

If the accessible name is helpful to screen reader users, consider if it might also be helpful to others. If that’s the case, consider providing a visible heading or other text label and using that as the accessible name.

Depending on the list’s context, use one of the following attributes to give it an accessible name.

aria-labelledby — when a visible label is available

If the list already has a heading or other visible label, use the aria-labelledby attribute on the list element (<ul>, <ol>, <dl>, <div role="list">) to make that visible label the list’s accessible name.

Example of aria-labelledby on an unordered list
<h3 id="nz-birds">Popular New Zealand birds</h3>
<ul aria-labelledby="nz-birds">
  <li>Kākāpō</li>
  <li>Kererū</li>
  <li>Kea</li>
</ul>

aria-label — when no visible label is available

If the list is not already associated with a heading or other visible label, and it does not make sense or it’s not possible to add a visible label, use the aria-label attribute to give the list an accessible name.

Example of aria-label on an unordered list
<ul aria-label="Popular New Zealand birds">
  <li>Kākāpō</li>
  <li>Kererū</li>
  <li>Kea</li>
</ul>

Note: If the list has a visible label, for example, a text heading or some icon, but also has an aria-label attribute, consider replacing aria-label with an aria-labelledby attribute pointing to the visible label. Otherwise, make sure that the aria-label value includes the visible label’s text or text equivalent, preferably at the beginning. This helps ensure that what a user sees (the visible label) is consistent with what a user hears (the aria-label value) when encountering the list with a screen reader.

Role

Ordered and unordered lists

By default, <ul> and <ol> elements have a role of list, and each <li> has a role of listitem.

However, if you’re building a custom ordered or unordered list, these are roles that need explicitly to be applied. See Custom ordered and unordered lists.

Description lists

The default roles exposed for <dl>, <dt> and <dd> elements are currently being revised and are expected in version 1.3 of the W3C’s ARIA specification.

For now, use native HTML description lists, which have reasonable accessibility support. Postpone the use of custom description lists until the relevant roles are settled.

For more, see the associationlist role — WAI-ARIA 1.3 Editor’s Draft — W3C.

Other accessibility considerations

Fixing Safari list behaviour with role="list"

Any CSS (for example, list-style: none;) that removes the markers from ordered or unordered lists will stop Safari from exposing the list as a list to assistive technologies. That is, Safari will not expose the affected <ul> or <ol> as having a role of list. Accordingly, the VoiceOver screen reader will not identify such elements as lists to the user.

To ensure that an ordered or unordered list with no list markers is exposed as a list in Safari, add role="list" to the <ol> or <ul>.

For more, see “Fixing” Lists — Scott O’Hara.