WCAG 4.1.2 Name, Role, Value: Tests And Fixes

WCAG 4.1.2 asks that every control on a page, from a simple link to a custom slider, tells assistive technology three things through code: what it is called (its name), what kind of thing it is (its role), and its current state or value. A screen reader can only announce what the code exposes, so a styled div that looks like a checkbox but says nothing about being checked leaves users guessing.

Quick facts

Level
A
Added in
WCAG 2.0
Principle
Robust
Applies to
Links, buttons, form fields, frames and every custom widget built with script
Most common failure
Clickable div or span elements with no role, name or state
Fast check
Browser accessibility inspector, then a screen reader pass

What WCAG 4.1.2 requires

WCAG puts it this way: for user interface components, "the name and role can be programmatically determined". Programmatically determined means software can read it from the code, not just a person from the screen. The criterion also asks that anything a user can change, such as checked, expanded, selected or a slider value, is available in code, and that changes are reported to assistive technology.

Native HTML does most of this for you. A button element has the button role and takes its name from its text. A checkbox input reports checked or not checked by itself. Problems start when teams build their own controls from generic elements.

Name, role and value, one at a time

Part	Meaning	Where it usually comes from	Heard as
Name	What the control is called	Text content, a label element, alt, aria-label or aria-labelledby	"Download report"
Role	What type of control it is	The HTML element, or a role attribute	"button", "link", "tab"
State or value	Its current condition or setting	Native behaviour, or attributes like aria-expanded, aria-checked, aria-selected	"collapsed", "checked", "3 of 5"

For more on how names are worked out, see our page on ARIA labels.

Who relies on it

Screen reader users hear the name, role and state of every control they reach; without them, a page of controls becomes a page of guesses. Braille display users read the same information. Voice control users say a control's name to press it, so a nameless button cannot be spoken to. Switch and keyboard users depend on the role too, because it tells the browser which keys the control should accept.

Name role value WCAG failures, with fixes

Failure	What the user meets	Fix
div or span used as a button	No role, often not focusable	Use `button`
Icon-only button with no text	An unnamed button	Add visually hidden text or aria-label
Custom checkbox or switch	No checked state	Use a native input, or role and aria-checked kept in sync
Accordion or menu toggle	No sign it opened	Add aria-expanded and update it on every click
Tabs built from list items	A plain list, no selected tab	Use tablist, tab and tabpanel roles with aria-selected
iframe with no title	"Frame" with no purpose	Add a title that says what the frame holds
Link used as a button	Wrong role, wrong keys expected	Use a button for actions, a link for navigation

Adding a role is a promise. If you set role="tab", users expect arrow keys to move between tabs. Either build that keyboard behaviour or use a simpler native element.

Code example: a toggle that reports its state

Fails: a script makes the div clickable, but it has no role, no name of its own, no state, and keyboard users cannot reach it.

<div class="toggle on"></div>
<span>Dark mode</span>

Passes: a real button, named by its text, with a pressed state that script keeps up to date.

<button type="button" class="toggle" aria-pressed="true">
  Dark mode
</button>

A screen reader announces the passing version as "Dark mode, toggle button, pressed". When the script flips the value to false, the next announcement says not pressed.

How to test for 4.1.2

Run an automated checker first. It reliably catches buttons, links and fields with no name.
Open the accessibility panel in your browser's developer tools and select each custom control. Read its role and name.
Use the control and watch the panel. States such as expanded or checked should change as you go.
Turn on a screen reader and tab through. Write down any control that sounds wrong, such as "clickable" with no role.
For tabs, menus, comboboxes and dialogs, check the expected keys and states against the ARIA Authoring Practices.

When an audit report lists name, role and value failures under WCAG 4.1.2, it is usually pointing at custom controls like these. Automated tools cannot tell whether a state actually updates, so steps 3 and 4 matter most. Our screen reader testing guide has the full method.

How 4.1.2 connects to other criteria

1.3.1 covers structure such as headings, lists and labels; this criterion covers the controls themselves.
2.5.3 goes a step further: the words on screen have to appear in the name.
2.1.1 makes sure the control can actually be used without a mouse.
4.1.3 handles updates that are not tied to a control.
4.1.1 Parsing used to sit next to it, until version 2.2 dropped it as obsolete.

W3C explains the intent in Understanding 4.1.2. Track it with the rest of Level A in the WCAG checklist.

Questions people ask

What is name, role, value in WCAG?

Criterion 4.1.2 requires every user interface component to expose its name and role in code, and to make its states and values available to assistive technology, including when they change.

Is 4.1.2 WCAG Level A or AA?

Level A, so it is part of every A, AA and AAA target. It dates back to version 2.0.

Does a native HTML button pass 4.1.2 automatically?

Mostly yes. A button element has the right role and takes its name from its text. It still fails if it contains only an icon with no text alternative.

Do I need ARIA to meet 4.1.2?

Only for custom widgets that have no native equivalent, such as tabs or tree views. For buttons, links, checkboxes and selects, use the HTML element and you need no ARIA at all.

Why was 4.1.1 removed while 4.1.2 stayed?

4.1.1 Parsing dealt with markup errors that modern browsers now repair in the same way, so W3C removed it in WCAG 2.2. Name, role and value problems still block users, so 4.1.2 remains.