ARIA treeitem requires accessible name

ARIA treeitem elements must not be missing an accessible name

Every element with role="treeitem" needs a programmatically determinable name that describes the node.

This appears in tree views such as navigation menus, file browsers, and hierarchical lists.

Without a name, screen reader and voice-control users cannot identify or target the item.

Why It Matters

Screen reader users rely on the accessible name to understand what each tree node represents. If a node is announced only as "tree item" with no label, it is unusable.

People using speech input need the visible label to match the accessible name so they can say the item by name. Mismatches or missing names block voice commands.

Clear names also reduce cognitive load for users who depend on consistent, predictable labels.

Common Causes

• Empty aria-label (e.g., aria-label="") or a label that is only whitespace.
• aria-labelledby points to an element that does not exist, is hidden, or has no text.
• Icon-only or background-image-only items with no associated text label.
• The visible text is wrapped in aria-hidden="true" or made inaccessible via role="presentation".
• Depending solely on the title attribute for naming (inconsistent support and poor UX).
• Dynamically generated tree nodes created without setting a label.

How to Fix

1. Prefer visible text as the label
   • Put meaningful, concise text in or referenced by the treeitem so it becomes the accessible name.
   • Ensure the text node is not hidden from assistive tech (avoid aria-hidden on the label container).
2. Use aria-labelledby when text is already present
   • Reference an existing visible label by id: aria-labelledby="label-id".
   • Make sure the referenced element exists in the DOM and has readable text.
3. Use aria-label when no visible text exists
   • Provide a short, descriptive label: aria-label="Project settings".
   • Do not leave aria-label empty.
4. Match visible label and accessible name (recommendation)
   • Keep the accessible name aligned with the on-screen label to support voice control (WCAG 2.5.3 Label in Name).
5. Hide decorative icons
   • Mark purely decorative icons as aria-hidden="true" so they do not interfere with naming.
6. Maintain names as content changes
   • If the node's label changes dynamically, update the accessible name accordingly.

Standards alignment: WCAG 2.2 — 4.1.2 (Name, Role, Value). Recommendation: 2.5.3 (Label in Name).

How to Test

Keyboard

• Tab to the tree. Use Arrow keys to move between nodes.
• Confirm each focused node has a clear, non-empty name announced by assistive tech.

Screen reader

• NVDA/JAWS (Windows): Focus the tree and move with Arrow keys. Listen for the item name, level, and state.
• VoiceOver (macOS): Interact with the tree and use VO+Arrow keys. Ensure each item is announced with its label.

Mobile/touch

• iOS VoiceOver or Android TalkBack: Swipe through tree items. Each item should speak a meaningful label.

Quick checklist

• Each treeitem has a non-empty accessible name.
• aria-labelledby references valid, visible text.
• aria-label is used only when needed and is not empty.
• Visible label matches the accessible name where practical.
• Decorative icons are aria-hidden.
• No label text is hidden from the accessibility tree.

Good Example

<ul role="tree" aria-label="Project">
  <li role="treeitem" aria-expanded="true" tabindex="0" aria-labelledby="node-docs">
    <span id="node-docs"><span class="icon" aria-hidden="true">📁</span> Documents</span>
  </li>
  <li role="treeitem" tabindex="-1" aria-labelledby="node-readme">
    <span id="node-readme"><span class="icon" aria-hidden="true">📄</span> Readme.md</span>
  </li>
  <li role="treeitem" tabindex="-1" aria-label="Archive"></li>
</ul>

Why it’s good

• Each node has an accessible name from visible text or aria-label.
• Decorative icons are hidden from assistive tech.
• aria-labelledby points to existing elements with meaningful text.

Bad Example

<ul role="tree">
  <li role="treeitem" tabindex="0"><span class="icon"></span></li> <!-- icon only, no name -->
  <li role="treeitem" aria-label="" tabindex="-1"></li> <!-- empty aria-label -->
  <li role="treeitem" aria-labelledby="missing-id" tabindex="-1"></li> <!-- broken reference -->
  <li role="treeitem" tabindex="-1"><span aria-hidden="true">Logs</span></li> <!-- label hidden from AT -->
</ul>

What’s wrong

• No programmatic name or empty names.
• aria-labelledby references an element that does not exist.
• The only visible label is hidden from assistive technologies.

Quick Checklist

• role="treeitem" has a non-empty accessible name.
• Prefer visible text or aria-labelledby to reference it.
• Use aria-label only when no visible label exists.
• Do not rely on title for the accessible name.
• Ensure referenced ids exist and contain readable text.
• Hide decorative icons with aria-hidden="true".
• Keep visible label and accessible name aligned for voice control.