WCAG 4.1.2 Name, Role, Value

Every UI component built with markup must expose a programmatic name, role, and value, plus state changes via accessibility APIs. The single criterion that underpins every ARIA pattern.

Normative spec: https://www.w3.org/TR/WCAG22/#name-role-value
Last verified: 2026-04-27
Byline: Editorial team

What this Level A success criterion requires

For every user interface component built with markup — whether native HTML, a framework primitive, or a custom widget — assistive technology must be able to programmatically determine three things and observe their changes:

Name — the accessible label.
Role — the kind of widget (button, combobox, tab, etc.).
States, properties, and values — aria-checked, aria-expanded, the current value of a slider, etc., plus notifications when those change.

This criterion is Level A. It is the foundation of every other ARIA success criterion. Failing it is one of the most common reasons audits flag a site, accounting for around 30% of all distinct issues recorded in the WebAIM Million 2024 report.

Why it matters

Without programmatic exposure, screen readers, switch devices, voice control, and braille displays cannot describe a control to the user. A “Save” button rendered as a styled <div> with no role and no keyboard handler is invisible to assistive technology — the user hears nothing, can move focus to nothing, and has no idea what the control does.

What a passing implementation looks like

For native elements: nothing extra is required. <button>Save</button> exposes a name (the text content), a role (button), and changes its focused state automatically as the user moves through the page.

For custom widgets: the author must explicitly provide every layer:

Name via aria-label, aria-labelledby, or a wrapping <label>.
Role via the role attribute (or ElementInternals.role on a custom element).
State via aria-checked, aria-expanded, aria-selected, aria-pressed, etc., kept in sync with the visible UI.
Value via aria-valuenow (plus aria-valuemin, aria-valuemax, and optionally aria-valuetext).
Change notifications — for live regions, aria-live and role="status" or role="alert".

How accessibility APIs enter the picture

Browsers maintain an accessibility tree parallel to the DOM. Each node has a name, role, state, and value. When the DOM updates, the tree updates. When the tree updates, the engine notifies the OS accessibility API:

macOS — AX API (NSAccessibility).
Windows — UI Automation (UIA), with IAccessible2 still used by older AT.
Linux — AT-SPI 2.

Each of Chromium (Blink), WebKit, and Gecko maps the DOM/ARIA layer to those platform APIs. The mappings are documented in Core-AAM, HTML-AAM, and ARIA-AAM.

Common failure modes

Custom checkbox without aria-checked. Visual state changes, programmatic state never updates. aria-checked must be "true" or "false" (or "mixed" for tri-state). The empty string is a bug.
Tab without aria-selected. A role="tab" element must declare aria-selected="true" on the active tab. Otherwise screen readers announce all tabs as un-selected.
Toggle button using only colour. Use aria-pressed="true" / "false" so AT knows the toggled state regardless of palette.
Disabled control with aria-disabled but no visual style. AT announces “dimmed” but the user sees a normal-looking button. The reverse — visual disabled style without aria-disabled — is just as broken: AT thinks the control is enabled.
Live region created at update time. As covered in /aria/states-and-properties, the region must be in the DOM before its content changes; otherwise no announcement fires.

Verification

Automated checkers (axe, the Chromium DevTools Accessibility tab, the Firefox Accessibility Inspector, and Safari’s Accessibility Audit) flag missing roles and missing accessible names with high precision. They cannot tell you whether the announced wording is correct; that needs human review with a real screen reader.

A typical verification protocol for a custom widget:

Build the widget; run axe on the page (target: 0 violations).
Tab through the page; verify focus order matches visual order.
Read the page with NVDA + Firefox on Windows, then VoiceOver + Safari on macOS. Confirm name, role, and state are announced correctly at each focus stop.
Trigger every state change (open, close, select, toggle); confirm AT announces the new state within 1 second.

Cross-engine support

The Name/Role/Value mappings have been stable across all three engines since the AAM specs reached CR in 2017–2018; the more recent ARIA 1.2 additions (aria-description, aria-details revisions) are in interop tests at about 90% pass-rate as of 2024.