# ARIA attributes must conform to valid values

> Canonical HTML version: https://rocketvalidator.com/accessibility-validation/axe/4.11/aria-valid-attr-value
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

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](https://www.w3.org/TR/wai-aria-1.1/#state_prop_def).

### 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

```html
<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

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

### Incorrect: Invalid Token Value

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

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

### Correct: Valid Token Value

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

### Incorrect: Invalid Tristate Value on a Checkbox

```html
<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

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

### Incorrect: Invalid Value for `aria-sort`

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

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

### Correct: Valid Value for `aria-sort`

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

### Incorrect: Non-Existent ID Reference

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

### Correct: Valid ID Reference

```html
<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.