# Elements with ARIA roles must have all required ARIA attributes.

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

When an HTML element has an explicit ARIA `role`, certain attributes may be required for that role to function correctly. If those attributes are missing, assistive technologies cannot communicate the element's full state, value, or structure to users. For example, a screen reader encountering a `role="checkbox"` without `aria-checked` has no way to tell the user whether the checkbox is checked or unchecked. The control becomes unpredictable and unusable.

This affects screen reader users most directly, since they depend on ARIA attributes to understand interactive components. But it can also affect users of other assistive technologies, such as voice control software or braille displays, which rely on the same accessibility tree data.

Each ARIA role has a specification that lists its required states and properties. When a developer assigns a role but omits a required attribute, the behavior becomes undefined. Some browsers may fall back to a default value, but this behavior is inconsistent and should not be relied upon. A small number of roles have defined default values in the WAI-ARIA spec (for example, `aria-selected` defaults to `false` for the `option` and `tab` roles), but most required attributes have no such fallback.

This rule relates to WCAG 4.1.2 Name, Role, Value (Level A), which requires that the name, role, and state of all user interface components can be programmatically determined. When a required ARIA attribute is absent, the component's state or value cannot be determined, which is a failure of this criterion. It also relates to WCAG 1.3.1 Info and Relationships (Level A), since missing attributes can cause structural information to be lost.

Note that this rule only applies to elements with explicit ARIA roles. Native HTML elements like `<input type="checkbox">` already have built-in mappings that satisfy the required states and properties, so they do not need explicit ARIA attributes added.

## Common roles and their required attributes

Here are some frequently used roles and the attributes they require:

- `role="checkbox"` requires `aria-checked`
- `role="slider"` requires `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
- `role="heading"` requires `aria-level`
- `role="combobox"` requires `aria-expanded` and `aria-controls`
- `role="scrollbar"` requires `aria-controls`, `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
- `role="meter"` requires `aria-valuenow`
- `role="separator"` (when focusable) requires `aria-valuenow`

The full list of required attributes for each role is defined in the [WAI-ARIA specification](https://www.w3.org/TR/wai-aria-1.2/).

## How to fix it

1. Identify the `role` attribute on the flagged element.
2. Look up the required states and properties for that role in the WAI-ARIA specification.
3. Add each missing required attribute with an appropriate value.
4. Make sure the attribute values are kept in sync with the actual state of the component. For example, when a custom checkbox is toggled, update `aria-checked` to match.

When possible, consider using native HTML elements instead of custom ARIA roles. A native `<input type="checkbox">` does not need `aria-checked` because the browser handles state communication automatically. Native elements are more reliable across browsers and assistive technologies.

## Examples

### Checkbox missing `aria-checked`

This custom checkbox has `role="checkbox"` but no `aria-checked` attribute. A screen reader cannot tell the user whether it is checked or not.

```html
<div role="checkbox" tabindex="0">
  Agree to terms
</div>
```

Add `aria-checked` with the correct value:

```html
<div role="checkbox" tabindex="0" aria-checked="false">
  Agree to terms
</div>
```

### Heading missing `aria-level`

A `role="heading"` without `aria-level` gives assistive technologies no information about the heading's position in the document hierarchy.

```html
<div role="heading">
  Section title
</div>
```

Add `aria-level` to specify the heading depth:

```html
<div role="heading" aria-level="2">
  Section title
</div>
```

Or better yet, use a native heading element:

```html
<h2>Section title</h2>
```

### Slider missing required value attributes

A slider needs `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` so users can understand the current value and its range.

```html
<div role="slider" tabindex="0">
  Volume
</div>
```

Add all three required attributes:

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

### Role with a default value (`tab`)

The `tab` role requires `aria-selected`, but the WAI-ARIA spec defines a default value of `false` for this attribute. Even though this technically passes, explicitly setting the value is clearer and more reliable across different browser and assistive technology combinations.

```html
<div role="tablist">
  <button role="tab" aria-selected="true">Tab 1</button>
  <button role="tab" aria-selected="false">Tab 2</button>
</div>
```