# ARIA role values must be valid.

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

When an HTML element has a `role` attribute, the value must match a role defined in the WAI-ARIA specification. If the value is misspelled, made up, or otherwise invalid, browsers and assistive technologies silently ignore it. The element then falls back to its implicit (default) role, which may be completely different from what the developer intended.

This matters most for screen reader users. Screen readers announce elements based on their role. A `<div>` with `role="buttn"` (a typo for `button`) will not be announced as a button. It will be treated as a generic container, so the user has no indication that the element is interactive. Keyboard behavior expectations also break down: users expect buttons to activate with Enter or Space, but a generic `<div>` does not receive keyboard focus by default.

## Why this matters

WCAG Success Criterion 4.1.2 (Name, Role, Value) at Level A requires that the role of every user interface component can be programmatically determined. When a `role` attribute contains an invalid value, the intended role is not communicated to assistive technologies. The element's semantics become ambiguous or wrong, and the interface becomes harder or impossible to use for people who rely on those semantics.

Success Criterion 1.3.1 (Info and Relationships) is also relevant, since an invalid role can obscure structural relationships between elements.

## Common causes

Most invalid role values come from typos (`"buton"` instead of `"button"`, `"navagation"` instead of `"navigation"`), outdated role names from draft specifications that were never finalized, or entirely invented values (`"card"`, `"container"`, `"header"`) that are not part of WAI-ARIA.

## How to fix it

1. Check the spelling of each `role` value against the [WAI-ARIA specification](https://www.w3.org/TR/wai-aria-1.2/#role_definitions).
2. Replace any invalid value with the correct WAI-ARIA role, or remove the `role` attribute entirely if a native HTML element already conveys the correct semantics.
3. If using fallback roles (multiple space-separated tokens), make sure every token in the list is a valid role. Some older browsers only read the first token, so the first value should be the preferred role.

Some commonly used valid roles: `button`, `link`, `navigation`, `main`, `dialog`, `alert`, `tab`, `tabpanel`, `menu`, `menuitem`, `search`, `searchbox`, `banner`, `complementary`, `contentinfo`, `form`, `region`, `status`, `log`, `progressbar`, `tree`, `treeitem`.

## Examples

### Invalid role value (typo)

The misspelled `role="nagivation"` is not a valid WAI-ARIA role. Assistive technologies will ignore it, and the element will not be recognized as a navigation landmark.

```html
<div role="nagivation">
  <a href="/home">Home</a>
  <a href="/about">About</a>
</div>
```

### Fixed: correct role value

```html
<nav>
  <a href="/home">Home</a>
  <a href="/about">About</a>
</nav>
```

Using the native `<nav>` element is the best fix here because it carries the `navigation` role implicitly. If a `<div>` is needed for some reason, use the correctly spelled role:

```html
<div role="navigation">
  <a href="/home">Home</a>
  <a href="/about">About</a>
</div>
```

### Invalid role value (invented role)

The value `"card"` is not defined in WAI-ARIA. It will be ignored.

```html
<div role="card">
  <h2>Product name</h2>
  <p>$29.99</p>
</div>
```

### Fixed: remove the invalid role

Since there is no WAI-ARIA role called `card`, remove the attribute. The content is still accessible through its heading and text.

```html
<div>
  <h2>Product name</h2>
  <p>$29.99</p>
</div>
```

If the element needs to be identified as a distinct region, use `role="region"` with an accessible name:

```html
<div role="region" aria-label="Product details">
  <h2>Product name</h2>
  <p>$29.99</p>
</div>
```

### Invalid role on an interactive element

```html
<input type="text" role="textfield" placeholder="Search">
```

The value `"textfield"` is not a valid role. The correct WAI-ARIA role for a text input is `textbox`, but `<input type="text">` already has an implicit role of `textbox`, so the attribute can simply be removed:

```html
<label>
  Search:
  <input type="text" placeholder="Search">
</label>
```

### Fallback roles

Multiple space-separated role values can be used as a fallback mechanism. Each value must still be valid.

```html
<div role="feed list">
  <article>Post 1</article>
  <article>Post 2</article>
</div>
```

Here, browsers that support `feed` will use it; those that do not will fall back to `list`. Both are valid WAI-ARIA roles, so this passes the rule.