ARIA attribute values must match the allowed set for each attribute

WCAG 4.1.2
Name, Role, Value

Content available in English only.

Accessibility isn’t just about avoiding violations — it’s about ensuring that everyone can use your product with confidence. This guide explains each rule’s intent, highlights common issues, and shows how to fix them according to WCAG and the European Accessibility Act (EAA).

These guidelines do not replace the official WCAG standards. They’re concise, developer-focused notes to help you identify and fix issues effectively.

ARIA values must match the spec — no guessing.

Why this matters and how to fix it

Why this matters

ARIA attributes convey state and behavior to assistive technologies. Using unsupported or incorrect values can cause screen readers to misinterpret or ignore the element, leading to inaccessible interactions.

How to fix this issue

Ensure each ARIA attribute uses a value from the allowed set defined in the WAI-ARIA specification. For example, `aria-pressed` only accepts `true`, `false`, or `mixed`. If the element’s behavior does not fit, use a different ARIA attribute or native HTML control.

Automated detection · Manual review recommended

Developer guidance

Invalid ARIA values often result from guessing or passing incorrect booleans in frameworks like React. Enforce allowed values with TypeScript unions, prop validation, or design system rules. Use the GetWCAG automated scanner to detect and prevent invalid ARIA attributes.

Code examples

Incorrect Implementation

<button aria-pressed="maybe">Toggle</button>

Correct Implementation

<button aria-pressed="true">Toggle</button>

Real-World Examples

Before

<div role="checkbox" aria-checked="yes">Subscribe</div> <!-- Screen reader ignores or misreads the state -->

After

<div role="checkbox" aria-checked="true">Subscribe</div> <!-- Screen reader correctly announces state -->

Manual testing

  1. 1. Inspect elements with ARIA attributes.
  2. 2. Verify each attribute value matches the allowed set in the WAI-ARIA specification.
  3. 3. Test with a screen reader to confirm that state and role are announced correctly.
  4. 4. If invalid, correct the value or switch to an appropriate native HTML control.
  5. 5. Integrate automated tests to catch future invalid values.
eu icon getwcag

Trusted by organizations across Europe working toward WCAG and EAA conformance