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:

• Accessible names and descriptions
• Roles, states and properties.

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.

<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.

<ul aria-label="Popular New Zealand birds">
  <li>Kākāpō</li>
  <li>Kererū</li>
  <li>Kea</li>
</ul>

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.