ARIA treeitem nodes should have an accessible name

The treeitem role represents an item within a hierarchical tree widget, commonly used for file explorers, nested navigation menus, or collapsible category lists. When a treeitem lacks an accessible name, screen readers announce something like “tree item” with no further context, making it impossible for users who rely on assistive technology to distinguish one item from another or understand the tree’s structure.

This issue primarily affects screen reader users, but it can also impact users of voice control software who need to reference elements by name to interact with them.

This rule relates to WCAG 2.1 Success Criterion 4.1.2 (Name, Role, Value), which requires that all user interface components have a name that can be programmatically determined. It also supports Success Criterion 1.3.1 (Info and Relationships), ensuring that information conveyed through structure is available to all users.

How to Fix It

You can give a treeitem an accessible name in several ways:

1. Inner text content — Place descriptive text directly inside the element.
2. aria-label — Add an aria-label attribute with a descriptive string.
3. aria-labelledby — Reference another element’s id that contains the label text.
4. title attribute — Use the title attribute as a last resort (less reliable across assistive technologies).

The accessible name should be concise and clearly describe the item’s purpose or content.

Examples

Incorrect: treeitem with no accessible name

<ul role="tree">
  <li role="treeitem"></li>
  <li role="treeitem"></li>
</ul>

Screen readers announce these items as “tree item” with no distinguishing label.

Incorrect: treeitem with only a non-text child and no label

<ul role="tree">
  <li role="treeitem">
    <span class="icon-folder"></span>
  </li>
</ul>

If the span renders only a CSS icon and contains no text, the treeitem still has no accessible name.

Correct: treeitem with visible text content

<ul role="tree">
  <li role="treeitem">Documents</li>
  <li role="treeitem">Photos</li>
  <li role="treeitem">Music</li>
</ul>

Correct: treeitem with aria-label

<ul role="tree">
  <li role="treeitem" aria-label="Documents">
    <span class="icon-folder"></span>
  </li>
  <li role="treeitem" aria-label="Photos">
    <span class="icon-folder"></span>
  </li>
</ul>

Correct: treeitem with aria-labelledby

<ul role="tree">
  <li role="treeitem" aria-labelledby="item1-label">
    <span class="icon-folder"></span>
    <span id="item1-label">Documents</span>
  </li>
  <li role="treeitem" aria-labelledby="item2-label">
    <span class="icon-folder"></span>
    <span id="item2-label">Photos</span>
  </li>
</ul>

Correct: Nested treeitem elements with accessible names

<ul role="tree">
  <li role="treeitem" aria-expanded="true">
    Documents
    <ul role="group">
      <li role="treeitem">Resume.pdf</li>
      <li role="treeitem">Cover Letter.docx</li>
    </ul>
  </li>
  <li role="treeitem" aria-expanded="false">
    Photos
  </li>
</ul>

Every treeitem in the tree — including nested ones — must have an accessible name. When building tree widgets, also ensure proper keyboard interaction (arrow keys for navigation, Enter/Space for activation) and correct use of aria-expanded on parent items that contain child groups.

Learn more:

Deque Reference

Deque University - How To Fix

→