# ARIA attributes must have valid values.

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

ARIA attributes each expect a specific type of value. When an attribute receives a value that doesn't match its expected type, browsers and assistive technologies may ignore the attribute entirely or fall back to a default. This can cause screen reader users to miss information about a component's state, purpose, or relationships. For example, setting `aria-hidden="yes"` instead of `aria-hidden="true"` means the attribute may be ignored, leaving an element visible to assistive technologies when the developer intended to hide it.

This rule relates to WCAG success criterion 4.1.2 (Name, Role, Value) at Level A. That criterion requires that the name, role, and state of user interface components can be programmatically determined. Invalid ARIA values break this contract because assistive technologies cannot reliably read a state or property whose value doesn't conform to the specification.

## Value types in WAI-ARIA

ARIA attributes fall into several value type categories. Each category has its own set of accepted values.

**True/false** attributes like `aria-hidden`, `aria-disabled`, and `aria-required` accept only `"true"` or `"false"`. Values like `"yes"`, `"no"`, `"1"`, or `"0"` are invalid.

**Tristate** attributes like `aria-checked` and `aria-pressed` accept `"true"`, `"false"`, or `"mixed"`. The `"mixed"` value indicates a partially selected or indeterminate state.

**True/false/undefined** attributes like `aria-expanded` accept `"true"`, `"false"`, or `"undefined"`. Setting the value to `"undefined"` indicates that the expandable/collapsible behavior does not apply.

**Token** attributes like `aria-live`, `aria-autocomplete`, and `aria-sort` accept a predefined set of keyword values. For instance, `aria-live` accepts `"off"`, `"polite"`, or `"assertive"`. Any other string is invalid.

**ID reference** attributes like `aria-labelledby` and `aria-describedby` expect one or more IDs pointing to other elements in the DOM. While the referenced elements don't strictly need to exist for the attribute value itself to be "valid" in a syntactic sense, referencing nonexistent IDs means the attribute has no practical effect.

**String** attributes like `aria-label` and `aria-placeholder` accept any non-empty text string.

**Number** attributes like `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` accept numeric values. Passing a non-numeric string is invalid.

## How to fix it

1. Check the WAI-ARIA specification for the attribute you're using to confirm which value type it expects.
2. Make sure boolean attributes use only `"true"` or `"false"`, not `"yes"`, `"no"`, `"1"`, or `"0"`.
3. For token attributes, use only one of the predefined keyword values listed in the spec.
4. For ID reference attributes, confirm the value contains valid ID strings. If you intend the attribute to point to another element, make sure that element exists in the DOM.
5. For numeric attributes, provide a valid number without extra characters or units.

Some user agents treat ARIA attribute values as case sensitive, so always use lowercase values (e.g., `"true"` instead of `"True"`).

## Examples

### Invalid boolean value

The value `"yes"` is not a valid boolean for `aria-hidden`. This attribute accepts only `"true"` or `"false"`.

```html
<p aria-hidden="yes">This text should be hidden from assistive technologies.</p>
```

### Fixed boolean value

```html
<p aria-hidden="true">This text should be hidden from assistive technologies.</p>
```

### Invalid token value

The value `"aggressive"` is not one of the accepted values for `aria-live`.

```html
<div aria-live="aggressive">Updates will appear here.</div>
```

### Fixed token value

The correct value is `"assertive"`.

```html
<div aria-live="assertive">Updates will appear here.</div>
```

### Invalid tristate value

The value `"partial"` is not valid for `aria-checked`. Tristate attributes accept `"true"`, `"false"`, or `"mixed"`.

```html
<div role="checkbox" aria-checked="partial">Select some items</div>
```

### Fixed tristate value

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

### Invalid numeric value

The `aria-valuenow` attribute expects a number, but it receives a string with a unit.

```html
<div role="slider" aria-valuenow="50%" aria-valuemin="0" aria-valuemax="100" aria-label="Volume">
</div>
```

### Fixed numeric value

```html
<div role="slider" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100" aria-label="Volume">
</div>
```

### Invalid boolean value on a required attribute

Using `"FALSE"` (uppercase) may be treated as invalid by some user agents.

```html
<input type="text" aria-required="FALSE" aria-label="Email">
```

### Fixed with lowercase value

```html
<input type="text" aria-required="false" aria-label="Email">
```