12k
All articles

What Is the Accessibility Tree?

Understand how browsers build the accessibility tree, compute roles and names, inspect it in DevTools, and test accessible controls with Playwright.

OpenReplay Team
OpenReplay Team
What Is the Accessibility Tree?

The accessibility tree is a second representation of a web page that the browser builds from the DOM for assistive technology, keeping each meaningful element’s role, accessible name, state and value while dropping most layout-only wrappers.

You run into it when an audit flags “button has no accessible name,” when a linter complains about a clickable div, or when Playwright’s getByRole can’t find an element you can see on screen. All three are reporting on the same structure. This article covers how the browser builds that tree, what each node holds, how to inspect it, and how to test against it.

Key Takeaways

  • Browsers build the accessibility tree from the DOM, native HTML semantics and ARIA attributes. Styling-only div and span elements usually get no node of their own.
  • Content hidden with display: none, visibility: hidden, the hidden attribute or aria-hidden="true" is excluded from the accessibility tree, even though it stays in the DOM.
  • In simplified form, an element’s accessible name comes from aria-labelledby first, then aria-label, then native labelling (<label>, alt), then text content, then title.
  • A <div> with a click handler has no button role in the tree, so screen readers don’t announce it as a control and keyboard users can’t reach it.
  • Playwright’s getByRole locator and ARIA snapshots work from roles and accessible names, so tests written with them fail on the same bugs that block assistive technology users.

How the Browser Builds the Accessibility Tree

Browsers build the accessibility tree from three inputs: the DOM, the built-in semantics of HTML elements, and any ARIA attributes. HTML-AAM defines how each HTML element maps to an accessible role, and Core-AAM 1.2 defines how ARIA roles, states and properties map to platform accessibility APIs.

The mapping from DOM to accessibility tree is not one-to-one. A <div> or <span> that exists only for flexbox or styling usually gets flattened away. Going the other way, HTML-AAM says that a <video> with the controls attribute exposes its built-in controls, such as play and volume, as child nodes mapped to roles like button and slider. None of those controls appears in the page’s DOM.

Hidden content is removed too. WAI-ARIA 1.2 excludes elements from the tree when they are not displayed (display: none, visibility: hidden, the HTML hidden attribute) or carry aria-hidden="true". A “visually hidden” or sr-only CSS class is a different case: it moves content off screen, so the content stays in the tree.

What Does an Accessible Node Contain?

Each node in the accessibility tree exposes up to four things: a role (what it is), a name (what it’s called), states (its current condition) and, for some controls, a value. Here is a labelled checkbox:

<label><input type="checkbox" checked> Email me product updates</label>

In Playwright’s ARIA snapshot format, the resulting node looks like this (illustrative):

- checkbox "Email me product updates" [checked]

The role is checkbox, the <label> supplies the name, and [checked] is the state. A checkbox communicates its information through its checked state. Value applies to controls such as textboxes and sliders, and the snapshot format puts it after a colon:

- textbox "Email": ada@example.com

For how individual roles are chosen and when to add ARIA roles yourself, see Understanding Accessibility Roles in HTML.

How Is the Accessible Name Computed?

In simplified form, a browser takes an element’s accessible name from the first source that provides one:

  1. aria-labelledby, pointing at other elements’ text
  2. aria-label
  3. Native labelling: a <label> element, or an image’s alt text
  4. The element’s own text content, for roles that allow naming from content (buttons, links)
  5. The title attribute, as a last resort

ARIA beats native labelling. If a button has visible text “Send” and aria-label="Submit form", a screen reader announces “Submit form”, and a voice-control user who says “click Send” may get no match. The full algorithm, including embedded controls and recursion, lives in Accessible Name and Description Computation 1.2.

How Do Screen Readers Use the Accessibility Tree?

Screen readers do not read the DOM. They read the accessibility tree through the operating system’s accessibility API, which the browser implements. Core-AAM’s mapping tables cover MSAA with IAccessible2 and UI Automation on Windows, the AX API (NSAccessibility) on macOS, and ATK/AT-SPI on Linux. The screen reader queries those objects for role, name and state, and listens for events such as focus changes. If a property never reaches the tree, the user never hears it.

How to Inspect the Accessibility Tree

Chrome DevTools and Firefox DevTools both show the accessibility tree directly: Chrome through the Accessibility tab in the Elements panel, Firefox through its Accessibility Inspector.

Chrome: open the Elements panel, select a node and open the Accessibility tab (it may sit behind the More Tabs » button). It shows the computed role, name and properties, plus where the name came from. Turn on Show accessibility tree to swap the DOM tree in the Elements panel for the full-page accessibility tree. The Chrome DevTools accessibility reference documents both. Chrome also has an internal chrome://accessibility page for browser-level debugging.

Firefox: the Accessibility Inspector opens from the page context menu (Inspect Accessibility Properties) or by right-clicking a node in the Inspector’s HTML pane and choosing Show Accessibility Properties. The inspector exposes Gecko’s own accessibility tree rather than information from the platform accessibility layer, so it shows the same output on every operating system.

Two Bugs the Accessibility Tree Reveals

The accessibility tree makes two common component bugs obvious: a clickable div with no button role, and an icon button with no accessible name. Each problem shows up as a missing role or a missing name. Vue and Angular templates produce the same output, because the tree only sees the rendered DOM.

A Clickable Div With No Button Role

// Before
<div className="btn" onClick={save}>Save</div>

// After
<button type="button" onClick={save}>Save</button>
# Before (illustrative)
- text: Save
# After
- button "Save"

A <div> with a click handler has no button role in the accessibility tree. A screen reader does not announce it as a control, and a keyboard user cannot Tab to it or activate it with Enter or Space. Session replays of this bug show the gap clearly: mouse users click the control without trouble, while keyboard users Tab straight past something that looks like a button but doesn’t exist as one in the tree.

An Icon Button With No Name

// Before
<button onClick={close}><svg aria-hidden="true">{/* icon */}</svg></button>

// After
<button aria-label="Close dialog" onClick={close}>
  <svg aria-hidden="true">{/* icon */}</svg>
</button>
# Before (illustrative)
- button
# After
- button "Close dialog"

An icon-only button with no text and no aria-label shows up as a button with an empty name, so a screen reader has nothing to announce except “button.”

Testing the Accessibility Tree With Playwright

Playwright’s getByRole locator finds elements by ARIA role, ARIA attributes and accessible name, following the W3C specs, and matches only non-hidden elements by default. A test that finds a control by role and name therefore also checks that the control exposes that role and name. ARIA snapshots go a step further: locator.ariaSnapshot() and page.ariaSnapshot() return a YAML view of the accessibility tree, and expect(locator).toMatchAriaSnapshot() asserts against it.

import { test, expect } from '@playwright/test';

test('save control is a real button', async ({ page }) => {
  await page.goto('/settings');
  await page.getByRole('button', { name: 'Save' }).click();
  await expect(page.locator('body')).toMatchAriaSnapshot(`- button "Save"`);
  await expect(page.locator('body')).toMatchAriaSnapshot(`- button "Close dialog"`);
});

Run this against the “before” markup and the getByRole call fails, for the same reason a screen reader user gets stuck. A template only has to match part of the tree, and a single-node template like these matches at any depth. If a template lists several nodes at the top level, they must share a parent and appear in the same order as in the tree. When a locator fails, log await page.ariaSnapshot() to see what the tree actually contains. These are the JavaScript names, and the other language bindings have equivalents. Playwright’s documentation also says role-based locators do not replace accessibility audits and conformance testing, so treat them as early feedback.

Role and name data matter beyond test runners as well. Some AI-driven automation tools read a page’s semantic structure, which is one reason agentic browsers work best on semantic markup.

Conclusion

The accessibility tree is the version of your UI that assistive technology actually receives, and a missing role or empty name in it means the control is broken for those users. Open the Accessibility tab on your most-used custom component, check its role and name, and turn that check into a getByRole assertion so it stays fixed.

FAQs

Does adding role='button' to a div fix it in the accessibility tree?

Only partly. Adding role='button' gives the div a button node in the accessibility tree, so screen readers announce it as a button, but it adds no button behaviour. The div still needs tabindex='0' to join the Tab order and a keydown handler that runs the action on Enter and Space. A native button element provides focus and keyboard activation by default.

Does aria-hidden='true' stop keyboard users from focusing an element?

No. aria-hidden='true' removes an element and its descendants from the accessibility tree but has no effect on keyboard focus. A link, button or input inside an aria-hidden container can still receive Tab focus, so keyboard users land on a control that assistive technology cannot name. Setting aria-hidden='false' on a child does not re-expose it. To hide interactive content from everyone, use display: none or the hidden attribute.

How can I read an element's computed role and accessible name in automated tests?

Use automation commands rather than page scripts. The W3C WebDriver spec defines Get Computed Role and Get Computed Label commands, which ChromeDriver implements and WebdriverIO exposes as getComputedRole() and getComputedLabel(). Playwright offers toHaveRole() and toHaveAccessibleName() assertions for a single element, plus ariaSnapshot() for a YAML view of a whole subtree. All of these report the role and name that assistive technology receives.

Why did getByRole name matches change after upgrading to Playwright 1.65?

Playwright 1.65 stopped counting text the browser does not render as part of accessible names and ARIA snapshots. Text that is not assigned to a slot, or that sits directly inside a closed details element, no longer counts. This can change the results of getByRole() with a name option, ariaSnapshot() output and toMatchAriaSnapshot() assertions, so expected names must match only the text the browser actually renders.

Open-source session replay

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.