Interactive Reference • WAI-ARIA 1.2 • Free
ARIA Roles & Attributes Reference
The complete interactive WAI-ARIA reference. Search roles and attributes, explore screen reader behavior, compare ARIA with native HTML, and test markup in a live playground.
25Roles
20Attributes
LivePlayground
Screen ReaderBehavior
Showing 47 of 47 items
Quick Comparisons
aria-label vs aria-labelledby vs aria-describedby
role="button" vs <button>
aria-hidden vs display:none vs visibility:hidden
ARIA Roles27
button
widget
ARIA 1.0
Use <button> instead
An interactive element that triggers an action when activated by the user via click, touch, or keyboard.
checkbox
widget
ARIA 1.0
Use <input type="checkbox"> instead
An input that allows the user to toggle between checked, unchecked, and optionally mixed states.
combobox
widget
ARIA 1.2
Use <select> with <datalist> instead
A composite widget combining a text input with a popup that helps the user set the value of the input.
dialog
widget
ARIA 1.0
Use <dialog> instead
A window overlaid on the primary content, requiring user interaction. Typically a modal or non-modal dialog.
link
widget
ARIA 1.0
Use <a href> instead
An interactive reference to a resource; activating it causes navigation to that resource.
listbox
widget
ARIA 1.0
Use <select> instead
A widget that allows the user to select one or more items from a list of options.
menu
widget
ARIA 1.0
A widget offering a list of actions or functions the user can invoke. Behaves like a desktop application menu.
menuitem
widget
ARIA 1.0
An option in a menu or menubar. Must be contained within a menu, menubar, or group within those.
option
widget
ARIA 1.0
Use <option> instead
A selectable item within a listbox, combobox popup, or select.
progressbar
widget
ARIA 1.0
Use <progress> instead
Displays the progress of a long-running task, either determinate (known percentage) or indeterminate.
radio
widget
ARIA 1.0
Use <input type="radio"> instead
One option within a radio group; only one radio in the group can be checked at a time.
slider
widget
ARIA 1.0
Use <input type="range"> instead
An input where the user selects a value from a given range by moving a thumb along a track.
switch
widget
ARIA 1.1
A toggle that represents an on/off value, similar to a checkbox but with clear binary semantics.
tab
widget
ARIA 1.0
A grouping label for a tabpanel, used within a tablist to enable switching between panels.
tabpanel
widget
ARIA 1.0
A container for the content associated with a tab. Shown or hidden based on the active tab.
textbox
widget
ARIA 1.0
Use <input type="text"> or <textarea> instead
A single-line or multi-line text input field where the user can enter free-form text.
tooltip
widget
ARIA 1.0
Use title attribute (limited) instead
A contextual popup displaying a short description for an element, shown on hover or focus.
banner
landmark
ARIA 1.0
Use <header> (when not nested) instead
Identifies the site-wide header, usually containing the logo, site title, and global navigation.
navigation
landmark
ARIA 1.0
Use <nav> instead
A collection of navigational links for the site or page. Maps directly to the <nav> element.
main
landmark
ARIA 1.0
Use <main> instead
Identifies the primary content of the page. There should be only one visible main landmark per page.
search
landmark
ARIA 1.0
Use <search> (HTML 5.2+) instead
Identifies a region containing search functionality, typically a search form or input.
region
landmark
ARIA 1.0
Use <section> (when labelled) instead
A perceivable section of the page with a specific purpose that should be included in a landmark summary.
contentinfo
landmark
ARIA 1.0
Use <footer> (when not nested) instead
Identifies the site-wide footer containing copyright, contact, and legal links.
heading
document
ARIA 1.0
Use <h1> - <h6> instead
A heading for a section of the page. Must include aria-level to indicate the nesting depth.
img
document
ARIA 1.0
Use <img alt="..."> instead
Identifies content that represents an image, whether a single <img> or a composite of elements forming an image.
alert
live-region
ARIA 1.0
A live region conveying important, time-sensitive information. Automatically announced by screen readers.
status
live-region
ARIA 1.0
Use <output> instead
A live region for advisory information that is not urgent enough for an alert. Announced at the next polite opportunity.
ARIA Attributes20
aria-label
property
global
Provides an accessible name for an element when no visible text label is present.
Value: string
aria-labelledby
property
relationship
References the ID of an element whose text content provides the accessible name.
Value: ID reference (space-separated list)
aria-describedby
property
relationship
References the ID of an element providing additional descriptive text for the current element.
Value: ID reference (space-separated list)
aria-hidden
state
global
Removes the element and its children from the accessibility tree while keeping it visually rendered.
Value: true | false | undefined
aria-expanded
state
widget
Indicates whether a collapsible section, menu, or other grouping controlled by this element is expanded or collapsed.
Value: true | false | undefined
aria-controls
property
relationship
Identifies the element(s) whose content or presence is controlled by the current element.
Value: ID reference (space-separated list)
aria-live
property
live-region
Indicates that an element will be updated dynamically and defines the politeness level for announcements.
Value: "off" | "polite" | "assertive"
aria-atomic
property
live-region
When true, the entire live region is re-read on any change. When false, only the changed nodes are announced.
Value: true | false
aria-checked
state
widget
Indicates the current checked state of checkboxes, radio buttons, and switches. Supports "mixed" for indeterminate.
Value: "true" | "false" | "mixed" | undefined
aria-disabled
state
widget
Indicates the element is perceivable but not operable. Unlike the HTML disabled attribute, it does not prevent focus.
Value: true | false
aria-selected
state
widget
Indicates the current selected state within widgets like tabs, listboxes, grids, and trees.
Value: true | false | undefined
aria-required
property
widget
Indicates that user input is required on an element before a form can be submitted.
Value: true | false
aria-invalid
state
widget
Indicates that the value entered does not conform to the expected format or validation rules.
Value: "true" | "false" | "grammar" | "spelling"
aria-pressed
state
widget
Indicates the current pressed state of a toggle button. Differentiates toggle buttons from regular buttons.
Value: "true" | "false" | "mixed" | undefined
aria-haspopup
property
widget
Indicates that the element can trigger a popup such as a menu, listbox, tree, grid, or dialog.
Value: "true" | "false" | "menu" | "listbox" | "tree" | "grid" | "dialog"
aria-current
state
widget
Indicates the current item within a set of related elements, such as the current page in navigation.
Value: "page" | "step" | "location" | "date" | "time" | "true" | "false"
aria-modal
property
widget
Indicates that a dialog is modal, meaning interaction is restricted to the dialog's contents.
Value: true | false
aria-valuenow
property
widget
Defines the current value for range widgets such as sliders, progress bars, and spin buttons.
Value: number
aria-errormessage
property
widget
References the ID of the element containing the error message for the current element when aria-invalid is true.
Value: ID reference
aria-activedescendant
property
relationship
Identifies the currently active descendant within a composite widget, enabling virtual focus without moving DOM focus.
Value: ID reference
Live ARIA Playground
Edit HTML with ARIA attributes — see the accessibility tree and screen reader output in real-time.
Type or paste HTML with ARIA roles and attributes. Changes update instantly.
Rendered Preview
Accessibility Tree
No accessible elements detected. Try adding ARIA roles or semantic HTML.
Screen Reader Would Announce
Nothing to announce.
ARIA vs Native HTML
| ARIA Role | Native HTML | Recommendation | Why |
|---|---|---|---|
| role="button" | <button> | Use native <button> | Native buttons include keyboard support, focus management, and form submission for free. |
| role="link" | <a href="..."> | Use native <a> with href | Native links are focusable, support right-click and middle-click, and are recognized by crawlers. |
| role="checkbox" | <input type="checkbox"> | Use native checkbox | Native checkboxes handle checked state, keyboard toggling, and form data automatically. |
| role="radio" + role="radiogroup" | <input type="radio"> in <fieldset> | Use native radio inputs | Native radios handle mutual exclusion, arrow key navigation, and group labelling via fieldset/legend. |
| role="textbox" | <input type="text"> or <textarea> | Use native input/textarea | Native inputs include built-in validation, autocomplete, and mobile keyboard optimization. |
| role="navigation" | <nav> | Use native <nav> | The <nav> element automatically creates a navigation landmark without requiring role. |
| role="banner" | <header> (top-level) | Use native <header> | A top-level <header> element automatically maps to the banner landmark role. |
| role="contentinfo" | <footer> (top-level) | Use native <footer> | A top-level <footer> element automatically maps to the contentinfo landmark role. |
| role="main" | <main> | Use native <main> | The <main> element provides the main landmark and is recognized by skip-navigation implementations. |
| role="heading" aria-level="N" | <h1> through <h6> | Use native heading elements | Native headings are recognized by browser outline algorithms, screen reader quick navigation, and SEO. |
| role="list" + role="listitem" | <ul>/<ol> + <li> | Use native list elements | Native lists provide automatic item counting and nesting semantics to screen readers. |
| role="img" | <img alt="..."> | Use native <img> with alt | Native img elements are optimized for lazy loading, responsive sizes, and alt text handling. |
| role="dialog" | <dialog> | Use native <dialog> | The native dialog element provides built-in modal behavior, focus trapping, and Escape to close. |
| role="progressbar" | <progress> | Use native <progress> | The native progress element handles determinate/indeterminate states with built-in accessibility. |
| role="slider" | <input type="range"> | Use native range input | Native range inputs provide keyboard support, min/max handling, and step increments automatically. |
Common ARIA Mistakes
Div used as a button
Keyboard users cannot activate the element; screen readers do not announce it as a button.
Missing alt text on images
Screen reader users have no idea what the image conveys; fails WCAG 1.1.1.
aria-hidden on focusable elements
Screen reader users land on the element via Tab but hear nothing; extremely confusing.
Missing form labels
Screen readers announce the field as an unlabelled text input; fails WCAG 1.3.1 and 3.3.2.
Color as the only indicator
Users who cannot perceive color miss the error state; fails WCAG 1.4.1.
Missing skip navigation link
Keyboard users waste significant time tabbing past repetitive navigation; fails WCAG 2.4.1.
Auto-playing media without controls
Interferes with screen reader audio; users cannot stop the media; fails WCAG 1.4.2.
Incorrect heading hierarchy
Screen reader users navigating by heading get a broken outline; fails WCAG 1.3.1.
Focus not managed in single-page apps
Screen reader users are stranded at the top of the old page or in limbo; fails WCAG 2.4.3.
Using role='menu' for site navigation
Screen readers switch to application mode, breaking normal link navigation expectations.
Frequently Asked Questions
Essential Accessibility Resources
Comprehensive tools, checklists, and guides to help you create inclusive digital experiences
Top Pick
How to Use ARIA: Roles, States & Properties
The cornerstone guide to using ARIA correctly: the five rules of ARIA, when native HTML wins, roles vs states vs properties, accessible names (aria-label vs aria-labelledby vs aria-describedby), landmark roles, the aria-hidden traps that break keyboard users, live regions, and the most common ARIA mistakes, mapped to WCAG 2.2
how to use aria
using aria
wai-aria
+3 more
Top Pick
ARIA Landmarks & Page Structure Guide
Landmarks and headings are the two maps a screen reader user navigates by, so an accessible page has to put its structure in the markup. Covers the eight landmark roles and the HTML that provides them, the scoping rule where header and footer are only landmarks at the top level, the section trap where a section is not a landmark until it has an accessible name, one main and naming repeated regions, the heading map and the debunked HTML5 document outline, complete coverage and reading order, and how NVDA, JAWS, and VoiceOver navigate by structure, mapped to WCAG 2.2
semantic html accessibility
semantic html
Web Accessibility Statistics 2026
Sourced, dated figures on disability, WCAG failure rates, screen readers, lawsuits, regulation and cost
screen reader