ARIA Treeitem Needs Name

What this check actually flags

A tree widget is the file explorer pattern: role="tree" on the container, role="treeitem" on every node, and aria-expanded on the branches that open and close. Documentation sidebars, category pickers, folder browsers, org charts, and permission managers all lean on it. This check fires when any element carrying role="treeitem" ends up with no accessible name: no readable text content, no aria-label, no aria-labelledby, nothing the browser can hand to assistive technology.

The failure is invisible in a normal browser session, which is exactly why it survives code review. The node looks fine on screen, the label is right there in pixels. But NVDA or VoiceOver lands on it and announces something like "tree item, 2 of 14, collapsed" and then stops. The user knows a branch exists and where it sits in the list, and has no idea what it is. Multiply that by every node and the whole widget is dead weight for anyone relying on a screen reader.

Why I treat this as a blocker, not a nice-to-have

axe-core ships this as the aria-treeitem-name rule and rates it serious. It maps to WCAG success criterion 4.1.2, Name, Role, Value: the moment you claim a role, you owe assistive technology a name to go with it. A control that announces its role but not its identity is arguably worse than a plain div, because it promises interaction it cannot explain.

There is a practical SEO angle too. Trees almost always hold navigation, and the same build mistakes that strip names from the accessibility tree, icon fonts as the only content, empty shells hydrated after load, labels tucked behind aria-hidden, also hand crawlers weak or empty anchor text. Every time I have traced this issue in an audit, the root cause was a rendering or templating problem worth fixing on its own merits. It also drags down the Lighthouse accessibility score that stakeholders actually look at, and unnamed interactive controls are exactly the kind of finding accessibility complaints and demand letters get built on.

How a treeitem gets its name, and how it loses it

Browsers compute an accessible name in a strict order: aria-labelledby wins, then aria-label, then the element's own text content. That sounds hard to fail, yet teams manage it in very predictable ways:

• Icon-only nodes. The node is a folder glyph with no text, and nobody added a label attribute.
• aria-hidden on the label. A wrapper span carries aria-hidden="true", usually copy-pasted from an icon element, and it removes the visible text from name computation.
• Icon fonts and CSS-injected content. The visible "label" is a glyph painted by CSS. What reaches the accessibility tree is a meaningless private-use character, or nothing at all.
• Virtualized lists. The framework renders placeholder shells for scroll performance and fills them in later. Both audits and real users catch the empty state.
• Truncation scripts. Long labels get moved into a title attribute or a tooltip component, and the node itself is left hollow.

Choosing the right naming method

How to detect it

Start with axe DevTools on any page that renders the tree: it flags aria-treeitem-name by name and lists the exact offending nodes. Lighthouse runs axe-core under the hood, so its accessibility category catches this too and slots neatly into CI. For coverage beyond a single page, Screaming Frog (version 20 and up) can run axe accessibility checks during a crawl, which tells you every template that ships the broken component instead of leaving you to play whack-a-mole one URL at a time.

A quick console check works when you just want an answer right now:

[...document.querySelectorAll('[role="treeitem"]')]
  .filter(n => !n.innerText.trim()
    && !n.getAttribute('aria-label')
    && !n.getAttribute('aria-labelledby'))

Then do one manual pass with a real screen reader. NVDA is free on Windows, VoiceOver is built into macOS. Arrow through the tree and listen. Five minutes of that tells you more than any report.

How to fix it, step by step

1. Inventory the damage. Run axe or the console snippet and identify which component renders the unnamed nodes. It is nearly always one shared component, which makes this a cheap fix with wide reach.
2. Prefer visible text. Put the label inside the treeitem as real text. Visible text stays in sync with the UI, gets translated with everything else, and never goes stale.
3. Label icon-only nodes with aria-label that says what the node is, not what the icon looks like: "Invoices", never "folder icon".
4. Audit aria-hidden. Confirm no wrapper span or ancestor is hiding the label from the accessibility tree. This is the most common silent killer.
5. Name loading states. If nodes hydrate asynchronously, give the placeholder a name like "Loading" instead of shipping empty shells.
6. Re-test and lock it in. Verify with axe and a screen reader, then wire the rule into CI so a component refactor cannot quietly reintroduce it.

Questions that come up