Powered by
Names, roles & states
A Custom Checkbox, Switch or Radio Has No Name
A screen reader announces "checkbox, not checked" but never says what the checkbox is for, so people can't tell what they're turning on.
aria-toggle-field-nameWCAG 2.0Introduced in WCAG 2.0.Level AA — the minimum. Missing it blocks people outright.
- Status
- SeriousSerious — Significant friction, or information that is lost.CurrentScanners run this rule today.
- Owner
- DesignDevContentTest
- Audit
- Automated+ManualA scanner finds it; a person confirms the fix.
Why it matters
Toggle fields are controls you turn on or off: checkboxes, switches, radio buttons and checkable menu items. When they're built with ARIA roles instead of plain HTML, they need a name added by hand. ARIA is a set of attributes that tell assistive technology what a control is.
Without a name, a screen reader only says the role and the state. People can't tell "Subscribe to marketing emails" from "I agree to the terms". Voice control users can't say what to click.
Who it affects
| Who | What they experience | Impact |
|---|---|---|
| Screen reader users | They hear "switch, off" or "checkbox, not checked" with no hint of what it controls. | High impact |
| Voice control users | They can't say "click Dark mode" because the control has no name to match. | High impact |
| Low-vision users (magnification) | Affected if they use a screen reader with magnification, as many do. | Partial impact |
| Cognitive and neurodivergent users | When a nearby visual label isn't linked, the spoken and visible versions don't match, which is confusing. | Partial impact |
Business & product impact
| Area | Why | Impact |
|---|---|---|
| Legal | It fails WCAG 4.1.2 at Level A, the minimum. Australia's Disability Discrimination Act complaints and EN 301 549 both point to WCAG. | High impact |
| Conversion | Unnamed consent, filter or settings toggles can block sign-ups and checkouts entirely. | High impact |
| SEO | Search engines don't read these names in any useful way — no real benefit. | Low impact |
| Brand trust | A form someone can't complete feels careless, and people share that experience. | Moderate impact |
| Cost to fix | Usually a small fix in one shared component. Using native HTML inputs avoids it entirely. | High impact |
Fixing it in code
A custom switch with a visible label
Don't
<span>Dark mode</span>
<div role="switch" aria-checked="false" tabindex="0"></div>A screen reader says: “switch, off”
Do
<span id="dm-label">Dark mode</span>
<div role="switch" aria-checked="false" tabindex="0" aria-labelledby="dm-label"></div>A screen reader says: “Dark mode, switch, off”
aria-labelledby links the visible text to the control as its name.
A custom checkbox
Don't
<div role="checkbox" aria-checked="false" tabindex="0"></div> I agree to the termsA screen reader says: “checkbox, not checked”
Do
<label><input type="checkbox"> I agree to the terms</label>A screen reader says: “I agree to the terms, checkbox, not checked”
A native checkbox inside a label gets its name for free.
Designer's handoff note
Give every toggle a visible text label, not just an icon or colour.
In your specs, write the spoken result, for example "Dark mode, switch, off".
Quick test
Tool
NVDA (opens in a new tab) (free on Windows) or VoiceOver (opens in a new tab) on Mac
Checklist
- Pass
- You hear a clear name, then the role and state, like "Dark mode, switch, off".
- Fail
- You hear only the role and state, like "switch, off".
Check these at the same time
- A custom input field has no name
aria-input-field-name - A role is missing an ARIA attribute it needs
aria-required-attr - A button has no name a screen reader can say
button-name - A form field has no label
label
What a green scan still misses
A scanner checks that a name exists. It can't tell if the name is clear, matches the visible label, or describes what the toggle really does.
Reference
- Rule ID
aria-toggle-field-name- Raised by
- axe-core: “ARIA toggle fields must have an accessible name”
- WCAG
- 4.1.2 Name, Role, Value (opens in a new tab) · Level A · since WCAG 2.0
- Other standards
- EN 301 549 9.4.1.2 · RGAA 7.1.1
- Last reviewed
- 14 October 2026