Relationships Between ARIA Roles and Attributes
If an issue entry sent you here, you're in the right place. This article explains how the WAI-ARIA specification decides which aria-* attributes can be used with each role, and which validations check each kind of relationship. Some familiarity with HTML and ARIA helps, but no prior experience with assistive technology is needed.
What ARIA roles and attributes are
Roles say what an element is
WAI-ARIA (Accessible Rich Internet Applications) lets you add semantic information to HTML that doesn't have it, so assistive technology can present custom widgets and complex layouts accurately. A role, set with the role attribute, says what an element is, such as a checkbox, a tab, or a dialog.
States and properties say how it behaves
ARIA states and properties, the aria-* attributes, describe the element further: whether a checkbox is checked (aria-checked), how a heading is ranked (aria-level), or which element labels it (aria-labelledby). States usually change while the user interacts with the element, and properties usually don't.
Not every attribute fits every role
An attribute only makes sense on some roles. aria-checked means something on a checkbox, but nothing on a heading. That's why the specification defines, for every role, which attributes it requires, which it supports, and which it prohibits.
Why these relationships matter
- User experience – screen readers announce an element based on the combination of its role and its attributes. A combination the specification doesn't allow can hide critical information, or make the announcement misleading.
- Consistent behavior – browsers map roles and attributes to the platform accessibility APIs according to the specification. Combinations outside it may be exposed differently in each browser, or not at all.
- Maintainability – knowing which attributes are required, and which have default values, keeps your markup lean.
- Compliance – WCAG success criterion 4.1.2 Name, Role, Value requires the name, role, states, and properties of every user interface component to be programmatically determinable. Invalid role and attribute combinations are a common cause of failures.
Note: Before you add a role and its attributes, check whether a native HTML element already does the job. A native <input type="checkbox"> exposes its role and checked state without any ARIA. For more, refer to HTML Semantics and Accessibility.
The relationship types at a glance
Each role in the WAI-ARIA specification has a characteristics table. Most of the relationships below are listed there. Conditional rules appear in the text that describes the role.
| Relationship | Where the specification defines it | What it means for you | Example |
|---|---|---|---|
| Required | “Required States and Properties” | You must provide it | heading requires aria-level |
| Supported | “Supported States and Properties” | You can add it when it's needed | button supports aria-pressed |
| Inherited | “Inherited States and Properties” | Supported because a parent role supports it | slider inherits aria-valuetext from range |
| Prohibited | “Prohibited States and Properties” | You must not use it | generic prohibits aria-label |
| Conditional | The role's description | Allowed only in a specific context | aria-level on a row only inside a treegrid |
| Global | “Global States and Properties” (section 6.5) | Supported on every role, unless the role prohibits it | aria-describedby, aria-hidden |
| Implicit value | “Implicit Value for Role” | The value used when you don't set the attribute | separator defaults to aria-orientation="horizontal" |
| Deprecated | Marked on the attribute, or on the role's attribute list | Still works, but avoid it in new content | aria-grabbed, aria-dropeffect |
Each relationship in detail
Required attributes
A required attribute is one you must set whenever you use the role. Without it, assistive technology can't convey key information about the element, such as a heading's level or whether a checkbox is checked.
<div role="heading" aria-level="2">Shipping details</div>
<div role="checkbox" aria-checked="false" tabindex="0">Subscribe</div>The aria-required-attr validation flags roles that are missing a required attribute.
Supported attributes
A supported attribute is allowed on the role, but optional. Add it when it conveys something about the element, for example aria-pressed on a toggle button, or aria-expanded on a button that opens a menu.
<button type="button" aria-pressed="true">Mute</button>An attribute that a role doesn't support, require, or inherit isn't allowed on it. For example, button doesn't support aria-checked. For a toggle, use aria-pressed, or use the switch or checkbox role instead. The aria-allowed-attr validation flags attributes that aren't allowed on the element's role.
Note: Optional doesn't mean that any value works. Each attribute accepts specific values, such as true or false, a number, or a list of tokens. The aria-valid-attr-value validation flags values that aren't valid.
Inherited attributes
Roles are organized in a hierarchy, and each role inherits the attributes its parent roles support. For example, slider is a kind of range, so it supports aria-valuetext even though the attribute isn't listed in its own “Supported” row. You use inherited attributes the same way as supported ones: add them when they are needed.
Prohibited attributes
A prohibited attribute is one you must not use on the role. For example, generic, the role of a plain <div> or <span>, and none (also known as presentation) prohibit aria-label and aria-labelledby. These roles can't have an accessible name, so a name on them would be ignored, or announced inconsistently.
<!-- Avoid: aria-label is prohibited on a generic element -->
<span aria-label="Required">*</span>The aria-prohibited-attr validation flags prohibited attributes.
Conditional attributes
Some attributes are allowed on a role only in a specific context, usually when the element is inside a specific parent role. The row role is the main example: aria-level, aria-posinset, aria-setsize, and aria-expanded describe a position in a hierarchy, so the specification allows them on a row only when it is inside a treegrid. Authors must not use them on a row inside a table or a grid.
<div role="treegrid" aria-label="Files">
<div role="row" aria-level="1" aria-expanded="true">
<div role="gridcell">Documents</div>
</div>
</div>If you need these attributes in a grid, use the treegrid role for the container, and they become valid. The aria-conditional-attr validation flags attributes that are used outside their allowed context.
Global attributes
Global attributes are supported on every role, and on elements with no role at all, unless a role prohibits them. Examples include aria-describedby, aria-hidden, and aria-live. Even a global attribute is invalid on a role that lists it as prohibited. For example, aria-label and aria-labelledby are global, but generic and none prohibit them.
Implicit values
When you don't set an attribute, browsers use the role's implicit value. For example, separator and slider default to aria-orientation="horizontal", and slider defaults to aria-valuemin="0" and aria-valuemax="100". You only need to set the attribute when your widget differs from the default, for example a vertical slider.
Deprecated attributes
Deprecated attributes are still part of the specification, and browsers are expected to support them, but authors are advised not to use them in new content. They may be removed in a future version. Examples include:
aria-grabbedandaria-dropeffect, deprecated in ARIA 1.1. The specification expects to replace them with a new feature in a future version.- The global use of
aria-disabled,aria-errormessage,aria-haspopup, andaria-invalid, deprecated in ARIA 1.2. They are still supported on the roles that list them, but are deprecated on others, such asaria-invalidandaria-errormessageonbutton.
Deprecated roles are flagged by the aria-deprecated-role validation.
Which validation checks what
| Error | Validation |
|---|---|
| A required attribute is missing | aria-required-attr |
| An attribute isn't allowed on the role | aria-allowed-attr |
| An attribute is prohibited on the role | aria-prohibited-attr |
| An attribute is used outside its allowed context | aria-conditional-attr |
An attribute name doesn't exist, for example aria-lable | aria-valid-attr |
| An attribute value isn't valid | aria-valid-attr-value |
| A role is deprecated | aria-deprecated-role |
Practical tips
- Start with the role's characteristics table – before you write the markup, check the role's “Required”, “Supported”, and “Prohibited” rows in the specification.
- Read the role's description – conditional rules are in the text, not the table. Look for phrases like “MUST NOT” and “unless”.
- Test early – run automated validations, such as Evinced, while you develop, to catch errors that are easy to miss in a manual review.
- Choose the most accurate role – pick the role that matches the widget, instead of adding attributes to a role that almost fits.
- Follow the specification's changes – ARIA evolves, and an attribute's status can change between versions. ARIA 1.3 is still a working draft.
Conclusion
Every ARIA attribute has a relationship with the role it's used on: required, supported, inherited, prohibited, conditional, global, implicit, or deprecated. When you match the right attributes to the right roles, in the right context, assistive technology can announce your widgets reliably, and users get the information they need.