ARIA Role Reference
Web ToolsComplete reference for WAI-ARIA roles, states, and properties with usage examples, screen reader behavior, and accessibility guidance.. Free, private — all processing in your browser.
role="button"A clickable element that triggers an action. Use on non-<button> elements made interactive.
role="checkbox"A checkable input with states true, false, or mixed. Requires aria-checked.
role="radio"A selectable item in a group of mutually exclusive radio options.
role="tab"A tab control in a tablist that, when activated, displays its associated tabpanel.
role="tabpanel"The content container associated with a tab.
role="tooltip"Contextual popup describing an element, shown on hover or focus.
role="dialog"A modal or non-modal dialog window. Pair with aria-modal and aria-labelledby.
role="alertdialog"A dialog that conveys an alert and requires a response, e.g. confirmation prompts.
role="menu"A list of choices, often used for application menus and context menus.
role="menuitem"An option in a menu.
role="slider"An input where the user selects a value from within a range. Needs aria-valuenow/min/max.
role="switch"An on/off toggle, similar to checkbox but with on/off semantics.
role="navigation"A collection of navigational links. Maps to the <nav> element.
role="main"The main content of the document. One per page. Maps to <main>.
role="banner"Site-oriented header content, typically the masthead. Maps to <header> at page level.
role="contentinfo"Footer information about the document. Maps to <footer> at page level.
role="complementary"Supporting content that complements the main content. Maps to <aside>.
role="search"A search form or region used to search site content.
role="region"A significant section. Requires an accessible name via aria-label or aria-labelledby.
role="alert"An important, time-sensitive message. Announced immediately by screen readers.
role="status"An advisory message that is not as urgent as alert. Announced politely.
role="progressbar"Displays progress of a task. Use aria-valuenow/min/max.
role="list"A list of items. Maps to <ul>/<ol>.
role="listitem"A single item in a list.
role="table"Tabular data with rows and columns. Maps to <table>.
role="heading"A heading for a section. Requires aria-level. Prefer native <h1>–<h6>.
role="img"A container treated as a single image. Requires an accessible name.
role="presentation"Removes an element's implicit semantics (alias: none). Use for decorative markup.
A searchable reference for the ARIA roles you'll actually reach for, grouped by category — landmarks, widgets, live regions, structure, and window roles. Search by name or description, filter by category, and copy the role="..." attribute straight into your markup.
ARIA (Accessible Rich Internet Applications) roles tell assistive technology what an element is when the HTML tag alone doesn't say it. If you build a custom dropdown out of divs, a screen reader sees generic containers; add the right roles and it announces a real menu. This reference is here to help you pick the correct role and remember what each one requires.
One rule worth stating up front, because it's the most important thing about ARIA: prefer native HTML. A real button, nav, or input carries its role and behavior for free. Reach for ARIA roles only when you're building something HTML doesn't already provide, or patching markup you can't change to semantic elements.
ARIA Role Reference — key features
Complete ARIA catalog
All roles, states, and properties from WAI-ARIA 1.2 with explanations.
Categorized browsing
Landmark, widget, document structure, window, state, property categories.
HTML equivalent guidance
For each ARIA role, shows whether an HTML native element exists (and is preferred).
Screen reader behavior
Describes how major screen readers (NVDA, JAWS, VoiceOver) announce each ARIA element.
Usage examples
Code snippets showing correct ARIA usage in context.
Common mistakes
Pitfalls and anti-patterns to avoid for each role/attribute.
WCAG mapping
Which WCAG success criteria each ARIA attribute helps satisfy.
Offline reference
Loads once, works without additional network calls.
How it works
Each entry lists the role, its category, and a short description of what it means and what it commonly needs — for example, that a slider requires aria-valuenow/min/max, a region needs an accessible name via aria-label or aria-labelledby, or that many landmark roles map directly to native elements (navigation → nav, main → main, banner → header, contentinfo → footer).
The categories follow the ARIA model: landmark roles define page regions for navigation, widget roles describe interactive controls, live-region roles (alert, status, progressbar) announce dynamic updates, structure roles describe static content, and window roles cover dialogs. Filtering and search are instant and run entirely in your browser.
This is a curated set of the roles developers use most often — it is not the complete ARIA specification, which defines many more roles plus a full system of states and properties. Treat it as a fast lookup and starting point, then confirm details against the WAI-ARIA spec and the ARIA Authoring Practices Guide for the exact keyboard and state requirements of any pattern you implement.
When to use the ARIA Role Reference
Accessibility development
- →Building accessible components: Reference correct ARIA for custom comboboxes, dialogs, tabs, and other complex widgets.
- →Fixing accessibility issues: When an audit identifies missing ARIA, look up the exact attributes needed.
- →Screen reader testing: Understand what each ARIA attribute makes screen readers announce, so you can design for that audience.
Code review
- →Verify ARIA correctness: Check ARIA in PR changes against standards to catch misuse.
- →Anti-pattern detection: Identify role=\"button\" on divs, aria-hidden on focusable elements, and other common mistakes.
- →Accessibility pairing: Have an accessibility expert review ARIA usage against this reference during code review.
Learning
- →Onboarding accessible development: New developers learning ARIA can use this as a self-paced reference.
- →Accessibility training: Resource for teams building a11y-first products.
- →Exam prep: Reference for IAAP (International Association of Accessibility Professionals) certifications.
ARIA Role Reference in practice
Labeled button
Accessible name for custom button.
<div role=\"button\" tabindex=\"0\" aria-label=\"Close dialog\">X</div>
Screen reader announces: \"Close dialog, button\" (better: use <button aria-label=\"Close dialog\">X</button>)
Expanded state
Dropdown or accordion.
<button aria-expanded=\"false\" aria-controls=\"menu1\">Menu</button>
announces \"Menu, button, collapsed\" when expanded, aria-expanded flips to true
Live region
Announcing dynamic updates.
<div aria-live=\"polite\">3 items in cart</div>
when text changes, screen reader announces new content at next break in speech
Landmark
Page structure.
<nav aria-label=\"Main navigation\">...</nav>
screen reader users can navigate directly to this landmark announced as \"Main navigation, navigation landmark\"
Hidden decoration
Icon with adjacent text.
<span aria-hidden=\"true\">✓</span> Done
screen reader reads \"Done\" without the icon icon is purely visual decoration
Troubleshooting
⚠Prefer native HTML over ARIA
A <button>, <nav>, or <input> already has the right role and behavior. Adding ARIA to reinvent them is more code and more ways to get it wrong. The first rule of ARIA is: don't use ARIA if native HTML can do it.
⚠A role alone is not enough
Most widget roles require supporting attributes and keyboard handling. role="checkbox" needs aria-checked and space-key toggling; role="slider" needs aria-valuenow/min/max and arrow keys. The role sets expectations you then have to fulfill.
⚠This list is curated, not exhaustive
It covers the most-used roles. The full ARIA spec defines many more roles, states, and properties. For anything not listed, check the WAI-ARIA specification.
⚠Landmark roles are often redundant
Native elements already expose landmark roles (nav, main, header, footer, aside). Adding role="navigation" to a <nav> is redundant. Use explicit roles mainly on generic elements you can't change.
⚠role="presentation" removes semantics
presentation (alias none) strips an element's implicit role — useful for decorative markup, but applying it to interactive or meaningful content hides it from assistive tech. Use it deliberately.
How it compares
The authoritative sources are the W3C WAI-ARIA specification and the ARIA Authoring Practices Guide (APG), which give the complete role list, required states, and keyboard interaction patterns. This tool doesn't replace them — it's a quick reference for the common roles, so you don't have to scroll a long spec page to remember what role="status" does or which category a role belongs to.
Use this to jog your memory and grab attributes fast. For implementing a full widget pattern (a combobox, a modal dialog, a tab set), go to the APG for the complete keyboard behavior and state management, because a role alone doesn't make a component accessible.
ARIA Role Reference — FAQ
▶When should I use an ARIA role?
Only when native HTML can't express what you need. If you build a custom control from generic elements (divs, spans), roles tell assistive tech what it is. If a native element exists — button, nav, input — use that instead; it carries the role for free.
▶What's the difference between a landmark and a widget role?
Landmark roles (navigation, main, banner) define page regions so users can jump between sections. Widget roles (button, checkbox, slider) describe interactive controls. Live-region roles announce dynamic changes, and structure roles describe static content.
▶Does adding a role make my component accessible?
No. A role sets expectations that you must then meet with supporting attributes (like aria-checked or aria-valuenow) and keyboard interaction. The ARIA Authoring Practices Guide documents the full pattern for each widget.
▶Is this the complete list of ARIA roles?
No. It's a curated set of the roles developers use most, for quick lookup. The complete list — plus all states and properties — lives in the W3C WAI-ARIA specification.
▶What does role="presentation" do?
It removes an element's implicit semantics (the alias 'none' does the same), so assistive tech ignores its role. It's meant for decorative markup, like a table used purely for layout. Don't apply it to meaningful or interactive content.
Additional resources
- WAI-ARIA 1.2 specification — Authoritative W3C specification for ARIA roles, states, and properties.
- ARIA Authoring Practices — W3C guide to implementing common ARIA patterns with examples.
- MDN ARIA reference — MDN’s comprehensive ARIA guide.
- axe DevTools — Browser extension for automated accessibility testing.
- WebAIM accessibility — Leading web accessibility organization with extensive tutorials.
Related tools
All Web ToolsCharacter Map
Browse and copy any Unicode character including emoji, symbols, arrows, mathematical signs, and non-Latin scripts.
Color Blindness Simulator
Simulate how colors and images appear to users with protanopia, deuteranopia, tritanopia, achromatopsia, and other color vision deficiencies.
Color Contrast Checker
Check color contrast ratios between foreground and background for WCAG 2.1 AA and AAA compliance with live preview.
Heading Structure Checker
Analyze H1-H6 heading structure on any page — detect missing headings, multiple H1s, broken hierarchy, and accessibility problems.
HTML Entity Encoder/Decoder
Encode special characters to HTML entities (&, <, ", ©) or decode entities back to their literal characters.
HTML Formatter
Format, indent, and beautify HTML, XHTML, and HTML5 markup
Learn more
Explore more tools
200+ free tools that run in your browser.
Browse all tools →