ARIA Roles Reference
A working, searchable map of every WAI-ARIA role — what it does, the native HTML element that already gives you it for free, the states it requires, its keyboard pattern, and the parent/child roles it expects. Pick a role to see the full spec-accurate card, copy it as Markdown, and share the exact view. Built to push semantic HTML first: the first rule of ARIA is don’t use ARIA.
About this ToolHow it works, benefits & use casesTap to collapse
This ARIA Roles Reference is a working, searchable map of the WAI-ARIA roles developers actually reach for — across landmarks (banner, navigation, main, complementary, contentinfo, search, region, form), widgets (button, link, checkbox, radio, switch, slider, spinbutton, tab, tabpanel, menuitem, option, progressbar, tooltip), composite widgets that manage their own focus (tablist, listbox, combobox, menu, menubar, radiogroup, grid, tree), document-structure roles (heading, list, img, figure, article, table, separator, presentation), live regions (alert, status, log, timer, marquee), and window roles (dialog, alertdialog). Pick a role and the sticky detail card shows the native HTML element you should prefer instead, the states it requires versus the ones it merely supports, the parent and child roles it expects, the keyboard pattern users will assume, a copy-paste accessible example, and the WCAG criteria in play. Abstract roles are flagged so you never put them in markup, and the whole role can be copied as Markdown for a PR or doc. Search matches role names, descriptions, ARIA states, and HTML equivalents; the selected role lives in the URL so you can share an exact view.
How to Use
- 1Type a role name, ARIA state (like aria-checked), or HTML tag into the search box to filter the list — it matches names, descriptions, states, and native equivalents.
- 2Narrow with the category chips: Landmark, Widget, Composite widget, Document structure, Live region, or Window.
- 3Click any role in the list to load its full spec-accurate card in the sticky left column.
- 4Read the green “use this native element instead” callout first — if an element is listed, prefer it over the ARIA role.
- 5Check the required vs supported states, the required parent/child roles, and the keyboard pattern before hand-rolling the widget.
- 6Copy the role as Markdown (or the share link) to drop the reference into a PR, doc, or ticket.
Key Benefits
- Roles grouped into the six ARIA categories, including composite widgets that manage focus
- Surfaces the native HTML equivalent for every role so you can avoid ARIA when a real element exists
- Separates required states from supported states, so you know the minimum to ship a valid role
- Shows required parent and owned child roles (tab needs a tablist; listbox owns options)
- Lists the expected keyboard interaction pattern per the ARIA Authoring Practices Guide
- Flags abstract roles that must never appear in markup
- Copy any role as full Markdown, and share the exact selected role via URL
Common Use Cases
- Looking up the required states and keyboard pattern before building a custom tab, combobox, slider, or dialog
- Confirming a native element exists (e.g. <button>, <nav>, <progress>) so you can drop a redundant role
- Checking which parent a role needs — e.g. that an option must live inside a listbox
- Pasting a spec-accurate role reference into a code review as Markdown
- Teaching a team which landmark roles map to which semantic HTML5 elements
role="button"Widget
A control that performs an action when activated.
Use this native element instead
<button><input type="button"><input type="submit">Required states
accessible nameSupported states
aria-pressedaria-expandedaria-disabledaria-haspopupKeyboard interaction
- Enter — activate
- Space — activate
Example
<button type="button" onclick="save()">Save</button>4.1.2 Name, Role, ValueCommon mistakes
- role="button" on a <div> without tabindex="0" and key handlers
- Icon-only button with no accessible name
Full role="button" reference — paste into docs or a PR
# role="button" **Category:** Widget A control that performs an action when activated. ## Native HTML equivalent - `<button>` - `<input type="button">` - `<input type="submit">` ## Required states & properties - accessible name ## Supported states & properties - aria-pressed - aria-expanded - aria-disabled - aria-haspopup ## Required context (parent roles) - (none) ## Owned / allowed children - (none) ## Keyboard interaction - Enter — activate - Space — activate ## Example ```html <button type="button" onclick="save()">Save</button> ``` ## Relevant WCAG - 4.1.2 Name, Role, Value ## Common mistakes - role="button" on a <div> without tabindex="0" and key handlers - Icon-only button with no accessible name
First rule of ARIA: if a native HTML element or attribute gives you the role and behaviour you need, use it instead of an ARIA role. Native elements ship with keyboard support, focus, and states for free.
49 roles
A role is a promise to assistive tech
When you put role="tab" on an element you’re promising a screen reader it behaves like a tab — that it lives inside a tablist, exposes aria-selected, and moves with arrow keys. ARIA changes semantics, never behaviour: it won’t add keyboard handling, focus management, or state for you. This reference shows, for each role, exactly which states are required, which parent and child roles it expects, and the keyboard pattern users will assume.
The five rules of ARIA, in short
- Prefer a native element over a role — a
<button>beatsrole="button". - Don’t change native semantics (no
role="tab"on an<h2>). - Every interactive ARIA control must be keyboard operable.
- Don’t hide a focusable element with
aria-hiddenorrole="presentation". - Every interactive element needs an accessible name.
Was this tool helpful?
Share Your Experience
Help others discover this tool!
Related tools
- Progress Bar GeneratorGenerate linear, circular, stepped & indeterminate bars (gradient/striped/pulse) with ARIA and a live preview
- ARIA Label GeneratorGenerate accessible names and preview what a screen reader announces
- Focus Order ValidatorVisualize DOM order vs tab order and catch positive-tabindex bugs
- Screen Reader Text GeneratorGenerate sr-only / visually-hidden text + CSS, with a focusable variant
- Skip Link GeneratorGenerate skip links + reveal-on-focus CSS and focus-managed targets
- Keyboard Navigation TesterAnalyze HTML for keyboard accessibility and Tab through a live sandbox
Because the first rule of ARIA is: if a native HTML element or attribute already gives you the role, state, and keyboard behaviour you need, use it instead of an ARIA role. Native elements ship with focus management, keyboard handling, and states for free, whereas ARIA only changes how an element is exposed — it never adds behaviour. The card’s green callout names the element (for example role="button" → <button>, role="navigation" → <nav>) so you default to semantic HTML and reach for a role only when no element fits.
Required states are the ARIA attributes a role must have to be valid and meaningful — a checkbox needs aria-checked, a slider needs aria-valuenow/min/max, and almost every interactive role needs an accessible name. Supported states are commonly used optional ones such as aria-disabled, aria-orientation, or aria-describedby. The card shows required states as red chips and supported states as accent chips so you can see the minimum you have to set.