aria-treeitem-name
Web validation
treeitem role should have an accessible name.A treeitem is a selectable item in a hierarchical tree structure, often used in composite widgets. For people who use assistive technologies, it’s essential that each treeitem has an accessible name. This allows them to understand the purpose or content of each item within the tree.
The accessible name can be derived from text content, or explicitly defined using aria-label or aria-labelledby. Without it, assistive technologies cannot convey meaningful information, making the interface unusable.
Pass Patterns
treeitem named by its text content
This treeitem has visible text content, which provides its accessible name.
<div role="tree">
<div role="treeitem">Settings</div>
</div>treeitem named by an aria-label attribute
This treeitem uses an aria-label to provide an accessible name, even though there is no visible text.
<div role="tree">
<div role="treeitem" aria-label="User profile options"></div>
</div>treeitem named by an aria-labelledby attribute
This example uses aria-labelledby to reference another element containing the label text.
<span id="label1">Reports</span>
<div role="tree">
<div role="treeitem" aria-labelledby="label1"></div>
</div>Fail Patterns
An empty treeitem with no labeling attribute
This treeitem has no accessible name at all. No inner text or labeling attribute.
<div role="tree">
<div role="treeitem"></div>
</div>A treeitem with an empty aria-label attribute
This treeitem has an empty aria-label, which means its name is still missing.
<div role="tree">
<div role="treeitem" aria-label=""></div>
</div>A treeitem with an aria-labelledby and no corresponding element
This example uses aria-labelledby to point to a non-existent element, which results in no accessible name.
<div role="tree">
<div role="treeitem" aria-labelledby="missingLabel"></div>
</div>Try It Yourself
Using a screen reader
New to screen reader testing, or need a refresher?
Review this article first: Practical guides for using screen readers
- Load the page, open a screen reader.
- Navigate to a tree or treeitem structure on the page.
- Use arrow keys to move between
treeitemelements, and listen to what the screen reader announces.
Expected result: Each treeitem should be announced with a descriptive accessible name.
Actual result: If the name is missing, the screen reader may announce nothing or only a generic role like “tree item”.
Inspecting the browser dev-tools
- Open the Accessibility Tree panel.
- Select the
treeitemelement on the DOM tree.
Expected result: The Name field shows the text provided as the accessible name.
Actual result: If unnamed, Name is empty.
FAQ
Why is this validation considered a best practice?
Although not directly tied to a specific WCAG success criterion, providing accessible names for treeitem elements is critical for assistive technology users to understand the structure and content of a tree widget. It’s part of ensuring that all interactive components are operable and understandable.
Why is this issue marked as Serious?
Without accessible names, treeitem elements become invisible to assistive technology users. This severely limits their ability to navigate tree-based widgets and understand their context, leading to major barriers in functionality and user experience across screen readers and other assistive technologies.