How the Accessible Name Is Computed

Overview

The accessible name solves a precise interoperability problem: a DOM element can be visually identifiable without exposing a stable textual label to assistive technology. A button might contain an icon, an input might be labelled by nearby text, and a custom element might expose semantics through ARIA. Screen readers, speech-recognition systems, automated test tools, and browser accessibility trees all need the same answer to the question “what is this control called?” The Accessible Name and Description Computation 1.2 specification, usually called AccName 1.2, defines that answer as a deterministic text alternative calculation for elements represented in accessibility APIs.

The problem is not merely “find some text.” It is precedence, ownership, recursion, and exclusion. The algorithm decides whether author-provided references such as aria-labelledby override aria-label, whether native host-language features such as the HTML label element contribute, whether child text is allowed for a given role, and whether hidden nodes may be traversed. Without a common algorithm, the same markup could be announced differently across user agents, making WCAG conformance, automated testing, and accessibility API mappings unstable.

How it works

At the systems level, accessible-name computation sits between the DOM/CSSOM and the platform accessibility tree. A user agent parses HTML or another host language, applies WAI-ARIA semantics, maps the resulting role and properties through documents such as Core Accessibility API Mappings 1.2 and HTML Accessibility API Mappings, then exposes an accessibility object with a role, states, properties, and name. The name is not usually stored as one fixed DOM attribute. It is computed from an ordered set of possible sources and must be invalidated when relevant text, attributes, relationships, or hidden states change.

The core algorithm is recursive. It starts with a root element and checks whether the role allows naming and which sources are permitted by that role’s “nameFrom” definition in WAI-ARIA. Author sources have high precedence: aria-labelledby points to one or more ID references whose text alternatives are concatenated in reference order; aria-label supplies a direct string when allowed. If those do not apply, host-language mechanisms such as the HTML label element, alt on img, title in limited cases, caption-like constructs, or form-control labelling rules may apply. For roles that allow “name from contents,” descendant text and eligible embedded controls are flattened into a string, with whitespace normalization defined by the algorithm.

A subtle systems detail is that the accessibility tree and the DOM tree are not the same graph. aria-labelledby can cross DOM ancestry boundaries by ID reference, while CSS visibility and ARIA hidden states can remove nodes from normal accessibility exposure. AccName 1.2 therefore includes explicit hidden-node rules: hidden content is normally excluded, but hidden nodes can contribute when they are reached through a labelling traversal permitted by the algorithm. That distinction lets authors use visually hidden text or referenced off-screen labels without making unrelated hidden subtrees nameable by accident.

What the standard says

The central normative document is W3C Accessible Name and Description Computation 1.2. It defines “accessible name” and “accessible description,” the text alternative computation, precedence of sources, ID reference traversal, hidden-node handling, and whitespace flattening. WAI-ARIA 1.2 supplies the role taxonomy, including whether each role supports name from author, name from contents, both, or neither. ARIA in HTML defines where ARIA attributes are conforming in HTML, while the WHATWG HTML Living Standard defines native labelling constructs such as labelable elements, the label element, alt on images, and form-associated behavior. The accessibility API mapping documents specify how the computed result is exposed to operating-system accessibility APIs.

WCAG 2.2 uses the result rather than redefining it. Success Criterion 4.1.2, Name, Role, Value, requires that user interface components have a programmatically determinable name and role, and that states, properties, and values that can be set by the user are programmatically settable and notified. Success Criterion 2.5.3, Label in Name, requires that for user interface components with visible text labels, the accessible name contains the visible label text; the documented best practice is to put the visible label text at the start of the accessible name. WCAG 2.2 is the current W3C Recommendation; WCAG 2.1 remains widely referenced, but WCAG 2.2 added criteria and marked 4.1.1 Parsing as obsolete and removed it from conformance requirements.

The standards also define constraints that are easy to miss. Some roles prohibit naming, so adding aria-label to such elements does not create a conforming name. Some roles require an accessible name, for example many interactive widget roles in WAI-ARIA, while others only allow one. The HTML Standard requires that a label element’s for attribute, when present, reference the first element in the document with the matching id that is labelable; otherwise a nested labelable descendant may be associated. AccName then consumes those host-language associations as part of the computation rather than treating every nearby text node as a label.

Trade-offs

The main measurable trade-off is determinism versus author flexibility. aria-labelledby can assemble a name from multiple DOM nodes, and the order is exactly the order of the ID references, not visual order or DOM order. That is measurable by comparing the token sequence in the attribute with the resulting flattened string. The flexibility supports composite labels such as “Search, site-wide,” but it also creates a dependency graph: renaming, removing, duplicating, or hiding referenced ids changes the computed name. Duplicate ids are invalid in HTML and create ambiguous author intent; the HTML id lookup rule resolves to the first matching element for many DOM operations, which can make a failure appear stable while still being non-conforming.

There is also a trade-off between visible simplicity and speech-input reliability. WCAG 2.5.3 has no numeric ratio threshold; the documented test is textual containment of the visible label within the accessible name for applicable controls. A visible button labelled “Save” with aria-label="Store draft" fails that criterion because the visible label is not contained in the accessible name. A button labelled “Save” with aria-label="Save draft" satisfies the containment requirement, although putting “Save” first is the documented best practice. This is measurable as a string-containment check after normalization, but language, punctuation, and generated text can make simplistic checks unreliable.

Performance is usually a graph-walk issue rather than a rendering metric. A minimal implementation can count visited nodes and traversed ID references; the work is bounded by the relevant labelled subgraph when cycle detection is present. The specifications do not define timing thresholds for recomputation. User agents therefore optimize with dependency invalidation: changes to aria-label, aria-labelledby, text nodes inside referenced labels, hidden states, and role changes can invalidate the cached accessibility name. The trade-off is that aggressive caching risks stale accessibility trees, while conservative recomputation can add work in large dynamic documents.

Failure modes

Common failures come from source precedence. aria-labelledby overrides aria-label when both are present and the references produce a name, so an apparently correct aria-label can be ignored. Empty or broken ID references can leave a control unnamed. Icon-only buttons often fail when the SVG title is not mapped as the button’s name or when the icon is aria-hidden without a replacement label. Conversely, adding aria-label to a control with a visible label can cause a Label in Name failure if the visible words disappear from the accessible name. Another frequent failure is naming a container role that does not support or need a name while leaving the actual interactive descendant unnamed.

Hidden-content failures are diagnostic traps. A referenced hidden node may still be used as a label under AccName 1.2’s hidden traversal rules, but an unreferenced hidden descendant generally does not contribute. CSS generated content can also complicate diagnosis because text that appears visually may not be author-supplied DOM text in the expected place. The durable diagnostic method is to inspect the computed accessibility tree rather than infer from pixels. Browser developer tools commonly expose role and name, while platform accessibility inspectors expose the mapped accessibility object. Automated checks can compare the expected accessible name with the computed one by driving accessibility-tree queries, but a DOM textContent comparison is not equivalent to AccName.

Diagnosis should follow the precedence order. First identify the element that actually receives focus or activation. Then determine its computed role, because the role controls whether naming is allowed and whether content can be used. Next inspect aria-labelledby tokens in order, verify that each id is unique and resolves to the intended element, and compute the referenced text alternatives. Then check aria-label, native labels, alt or other host-language sources, and finally name-from-content rules. For WCAG 2.5.3, compare the visible text label with the final accessible name, not with intermediate sources.

A minimal implementation

A correct minimal implementation for ordinary HTML controls should avoid ARIA when native labelling is sufficient. For a text input, the minimal pattern is a label associated with the control: <label for="email">Email</label><input id="email" name="email" autocomplete="email">. The HTML label association supplies the accessible name “Email,” and AccName consumes that host-language relationship. For an icon-only button, a minimal pattern is <button aria-label="Close"><svg aria-hidden="true" focusable="false">…</svg></button>. The button role permits name from author, aria-label supplies the name, and the decorative graphic is removed from the accessibility tree.

When the visible label text is present, preserve it in the computed name. A minimal robust button is <button>Save</button>; no ARIA is needed because the button role allows name from contents. If extra context is required, aria-labelledby can combine visible and auxiliary text: <button id="b" aria-labelledby="b t"><span id="t">Save</span></button> is usually unnecessary, but it illustrates reference-order control. A more realistic form pattern is <span id="amount-label">Amount</span><span id="amount-unit">USD</span><input aria-labelledby="amount-label amount-unit">, which computes “Amount USD.” The ID reference order, not layout order, defines the resulting token order.

For custom elements, the minimal implementation must expose both role and name through current platform mechanisms. A custom control can use a host element with role="button", tabindex="0", keyboard activation for Enter and Space, and either text content or aria-label. Where form-associated custom elements are used, ElementInternals and ARIA reflection properties such as ElementInternals.ariaLabel can participate in exposing semantics, but they do not remove the need to follow AccName precedence and WCAG label-in-name requirements. The minimal rule is: choose one primary naming path, keep visible label words in the final name, verify the computed accessibility tree, and avoid redundant ARIA when the host language already defines the name.