Rule ID: ace-aria-valid-value

Confirm all ARIA attribute values conform to the allowed value types defined in the specification

WCAG 2.0 (A) - WCAG 2.2 (A) 4.1.2: Name, Role, Value Blind Deafblind Mobility Legal Risk

What This Rule Checks

ARIA attributes must have valid, correctly spelled values that correspond to predefined options. Incorrect or invalid values prevent assistive technologies from functioning properly, causing confusion and hindering accessibility.

Who Is Affected

This issue primarily affects: Blind users, who rely entirely on screen readers or braille displays to navigate and interact with content; Deafblind users, who rely on braille displays and cannot access visual or auditory content; Mobility users, who navigate using keyboards, switches, voice control, or other assistive input devices.

Why This Matters

Invalid ARIA attribute values cause unpredictable behavior across screen readers. Some may ignore the attribute entirely, others may default to unexpected values. This is a critical WCAG 4.1.2 violation affecting all assistive technology users.

How to Fix

To ensure ARIA attributes work correctly:

Check for Spelling Errors: Ensure values are spelled correctly, such as aria-hidden=”true”. Misspellings like aria-hidden=”rtue” will fail.

Use Allowed Values: Each ARIA attribute has a specific set of allowed values. For example, a checkbox role allows only true, false, or mixed as valid values. Any other value, like aria-checked=”on”, would be invalid.

Value Types:

Here are the allowed types of values for ARIA states and properties:

true/false: Accepts only true or false. The default is typically false.
tristate: Accepts true, false, or mixed, with a default of false.
true/false/undefined: Can be true, false, or undefined, where undefined indicates that the state or property is not set.
ID reference: Points to the ID of another element in the document.
ID reference list: Accepts a list of one or more ID references.
integer: Only accepts whole numbers.
number: Accepts any real number.
string: Can accept any text value.
token: Accepts a predefined set of values.
token list: Accepts a list of one or more predefined tokens.

Code Examples

Incorrect Markup Solutions:

Code example

<!-- Invalid aria-hidden value -->
<div aria-hidden="yes">
  Hidden content
</div>

<!-- Invalid aria-live value -->
<div aria-live="sometimes">
  Updates here
</div>

Copy

Correct Markup Solutions:

Code example

<!-- Valid aria-hidden value (true/false) -->
<div aria-hidden="true">
  Hidden content
</div>

<!-- Valid aria-live value (polite/assertive/off) -->
<div aria-live="polite">
  Updates here
</div>

Copy

Common Mistakes to Avoid

Using “yes”/”no” instead of “true”/”false” for boolean ARIA attributes.
Setting aria-level to 0 or negative numbers.
Using non-standard values like aria-live=”sometimes” or aria-sort=”both”.

AI Auto-Fix Available

This rule supports ACE™ AI Auto-Fix. When a violation is detected, ACE can automatically generate a code fix for review. The AI analyzes the specific element in context and proposes a targeted remediation that preserves your existing markup and styling. You can preview, modify, and approve the fix before it is applied.

Tip: Remember the first rule of ARIA: don’t use ARIA if a native HTML element can provide the same semantics. Native elements come with built-in keyboard handling and screen reader support that ARIA cannot replicate.

Related WCAG Criteria

4.1.2: Name, Role, Value