Goal
Ensure custom UI components expose name, role, and value to assistive technologies.
Success Criterion · WCAG 4.1.2
Name, Role, Value
For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies.
Level AWCAG 2.0Robust4.1 · Compatible
Copy button ready
What to do
For custom controls, ensure role, accessible name, states, and values are programmatically determinable and updated.
Why it matters
If assistive technologies can’t determine what a component is or its state, users can’t operate it.
Success criterion
What WCAG 4.1.2 requires
Summarized directly from the official Understanding document so teams can quote the requirement accurately.
For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies.
Intent
Why WCAG created this requirement
- Custom widgets must behave like real controls to AT.
- Name/role/state/value must be accurate and kept in sync.
- State changes must be communicated (ARIA states/properties).
Benefits
Who gains when you pass
- Screen reader users can understand and operate custom controls.
- Voice users can target elements by name and role.
- All users benefit from consistent and robust UI components.
Why it matters
User impact when this criterion fails
Summaries drawn from the Understanding document help you socialize impact statements with product stakeholders.
Users may not know what a control does or whether it is on/off.
Controls may be impossible to operate with AT if states aren’t exposed.
Overview
All interactive controls—especially custom widgets—must expose an accessible name and role, and must communicate current state/value (checked, expanded, selected, etc.) and updates to assistive technologies.
- Prefer native elements; use ARIA only when needed.
- Ensure `aria-expanded`, `aria-checked`, `aria-selected`, etc. reflect actual state.
- Keep accessible name stable and meaningful (see 2.5.3).
- Announce updates through appropriate ARIA patterns and live regions when needed.
Reference: All summaries and highlights originate from Understanding WCAG 4.1.2 and the W3C quick reference.
Fast facts
- Conformance level
- Level A
- WCAG version introduced
- WCAG 2.0
- Principle
- Robust
- Guideline
- 4.1 · Compatible
Examples
Make success tangible for teams
Share pass/fail snapshots to coach designers, engineers, QA, and content authors.
Custom toggle
Pass
Uses `role="switch"` with `aria-checked` updated on toggle.
Fail
Clickable div toggles visually but exposes no role or state.
Accordion
Pass
Button uses `aria-expanded` and controls region via `aria-controls`.
Fail
Accordion opens visually but AT receives no state change.
Evidence to keep
Document conformance decisions
Capture artifacts for VPATs, procurement reviews, and regression testing.
- Document ARIA patterns used for each custom widget type.
- Maintain a checklist for name/role/state/value for new components.
Official resources
Deep dives and supporting material
Keep these links handy when writing acceptance criteria or responding to audits.
Implementation checklist
Capture progress and blockers
- Use native controls wherever possible.
- For custom widgets, apply correct ARIA roles and properties.
- Provide accessible names for all controls (label, aria-label, aria-labelledby).
- Ensure state/value updates are reflected in ARIA attributes.
- Test with screen readers and accessibility tree inspection.
Testing ideas
Prove conformance with evidence
- Inspect accessibility tree: verify role, name, and state/value are correct.
- Operate custom widgets with keyboard and screen reader and confirm announcements.
- Change state (toggle, expand) and confirm AT is notified of the change.
Related success criteria