What version of WAI-ARIA does this cover?

This reference covers WAI-ARIA 1.2, the current W3C Recommendation as of 2023. Roles and attributes follow that specification.

What is the difference between required and supported attributes?

Required properties must always be present (e.g. aria-valuenow on a slider). Supported attributes are optional states and properties the role allows, such as aria-disabled or aria-label.

Can I use any HTML element with any ARIA role?

No. Each role lists its allowed host elements. Using a role on a semantically mismatched element (e.g. role="heading" on a ) works, but using native HTML elements (e.g. ) is always preferred over ARIA overrides.

What are abstract roles?

Abstract roles (command, composite, input, landmark, range, roletype, section, sectionhead, select, structure, widget, window) define the inheritance hierarchy. They must not be used directly in HTML — they exist for specification purposes only.

How do I know which role to pick for a custom widget?

Start with the widget that most closely matches your component's keyboard behavior. For example, a custom dropdown that opens on click and lets users pick one item maps to listbox/option. The ARIA Authoring Practices Guide (APG) on w3.org provides design pattern guidance.

ARIA Role Reference

Name: ARIA Role Reference
Availability: InStock
Author: Nham Vu

Search any WAI-ARIA role to see its required properties, allowed attributes, permitted HTML elements, and a code example.

Search roles

Select a role from the list to see its details.

Summary

Search any WAI-ARIA role to see its required properties, allowed attributes, permitted HTML elements, and a code example.

How it works

Type a role name or keyword into the search box to filter the role list.
Click any role card to expand its full detail panel.
Review required properties that must be present for the role to be valid.
Check supported attributes for optional states you can set.
Copy the provided code snippet directly into your HTML or component.

Use cases

Look up which aria-* attributes are required for a custom combobox.
Verify permitted HTML host elements before choosing a role.
Find the correct role for a custom UI widget (slider, tree, grid, etc.).
Review abstract roles to understand the ARIA inheritance hierarchy.
Share a quick reference link with teammates reviewing a PR.
Double-check role constraints while writing accessibility tests.

Frequently Asked Questions

Last updated: 2026-07-01 · Reviewed by Nham Vu