ARIA attributes must conform to valid values

ARIA attributes communicate essential information about the state, properties, and roles of interface elements to assistive technologies like screen readers and braille displays. When these attributes contain invalid values, the communication breaks down entirely. A screen reader might ignore the attribute, misrepresent the element’s state, or behave unpredictably — any of which can make content unusable.

This issue has a critical impact on users who are blind, deafblind, or have mobility impairments who rely on assistive technology to navigate and interact with web content. For example, if a checkbox uses aria-checked="ture" instead of aria-checked="true", a screen reader cannot determine whether the checkbox is checked, leaving the user unable to understand the form’s current state.

This rule maps to WCAG 2.0, 2.1, and 2.2 Success Criterion 4.1.2: Name, Role, Value (Level A), which requires that for all user interface components, the name, role, and value can be programmatically determined and set by assistive technologies. Invalid ARIA values violate this criterion because the value cannot be meaningfully determined.

How to Fix It

For every aria- attribute in your markup, confirm that its value:

1. Is spelled correctly — a typo like "flase" instead of "false" will cause a failure.
2. Is a permitted value for that specific attribute — each ARIA attribute accepts only certain value types.
3. Makes sense in context — the value must be meaningful for the role and state of the element.

Understanding Value Types

Different ARIA attributes accept different types of values. Here are the most common:

• true/false — Boolean values. Default is typically "false". Example: aria-hidden="true".
• tristate — Accepts "true", "false", or "mixed". Example: aria-checked="mixed" for a partially selected checkbox.
• true/false/undefined — Like true/false, but "undefined" explicitly indicates the property is not relevant.
• token — One value from a limited set of allowed strings. Example: aria-sort accepts "ascending", "descending", "none", or "other".
• token list — A space-separated list of one or more allowed tokens. Example: aria-relevant="additions text".
• ID reference — The id of another element in the same document. Example: aria-labelledby="heading-1".
• ID reference list — A space-separated list of element IDs. Example: aria-describedby="desc1 desc2".
• integer — A whole number with no fractional part. Example: aria-level="2".
• number — Any real number. Example: aria-valuenow="3.5".
• string — An unconstrained text value. Example: aria-label="Close dialog".

For a complete reference of which values each attribute accepts, consult the WAI-ARIA 1.1 Supported States and Properties.

Watch Out for Common Pitfalls

• Typos in boolean values — "ture", "flase", "yes", and "no" are all invalid for attributes that expect "true" or "false".
• Using wrong tokens — Attributes like aria-sort, aria-autocomplete, and aria-current only accept specific string values.
• Referencing non-existent IDs — If aria-labelledby points to an id that doesn’t exist in the document, the reference is invalid.
• Implicit defaults — Some roles change the default value of certain properties. For instance, aria-expanded on a combobox defaults to "false" rather than "undefined". Be aware of role-specific defaults.

Examples

Incorrect: Misspelled Boolean Value

<div aria-hidden="flase">
  This content should be visible to assistive technology.
</div>

The value "flase" is not a valid boolean. Assistive technologies may not be able to interpret the intended state.

Correct: Properly Spelled Boolean Value

<div aria-hidden="false">
  This content is visible to assistive technology.
</div>

Incorrect: Invalid Token Value

<button aria-pressed="yes">
  Bold
</button>

The aria-pressed attribute accepts "true", "false", or "mixed" — not "yes".

Correct: Valid Token Value

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

Incorrect: Invalid Tristate Value on a Checkbox

<div role="checkbox" aria-checked="partial" tabindex="0">
  Select all items
</div>

The aria-checked attribute on a checkbox role only accepts "true", "false", or "mixed". The value "partial" is not recognized.

Correct: Valid Tristate Value on a Checkbox

<div role="checkbox" aria-checked="mixed" tabindex="0">
  Select all items
</div>

Incorrect: Invalid Value for aria-sort

<th aria-sort="alphabetical">Name</th>

The aria-sort attribute only accepts "ascending", "descending", "none", or "other".

Correct: Valid Value for aria-sort

<th aria-sort="ascending">Name</th>

Incorrect: Non-Existent ID Reference

<input type="text" aria-labelledby="username-label">
<!-- No element with id="username-label" exists in the document -->

Correct: Valid ID Reference

<label id="username-label">Username</label>
<input type="text" aria-labelledby="username-label">

What This Rule Checks

The aria-valid-attr-value rule inspects every element that has one or more aria- attributes and verifies that each attribute’s value conforms to the allowed values defined in the WAI-ARIA specification. It checks for correct spelling, valid tokens, proper value types (boolean, integer, ID reference, etc.), and ensures that referenced IDs exist in the document.