Loading...
Loading content...
A single-page reference for the WAI-ARIA 1.2 roles, states, and properties you will actually use. Native HTML elements should always be your first choice — reach for ARIA only when no HTML equivalent fits.
First rule of ARIA
“If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of repurposing an element and adding an ARIA role, state, or property to make it accessible, then do so.” — WAI-ARIA Authoring Practices
Top-level page regions screen readers can jump between. Use the native HTML landmark elements when you can.
Site-wide header that contains site-oriented content (logo, search, primary navigation).
<header role="banner">…</header>A collection of navigational elements (links) for navigating the document or related documents.
Common states & properties
<nav aria-label="Primary">…</nav>The primary content of a page; one per page.
<main id="main-content">…</main>Content that complements but is meaningful alone (sidebars, related links).
<aside aria-label="Related articles">…</aside>Footer information about the parent document (copyright, contact, links).
<footer role="contentinfo">…</footer>A region containing a search facility.
<form role="search">…</form>A region with associated form controls. Only treated as a landmark when it has an accessible name.
A perceivable section of content. Must have an accessible name.
Common states & properties
Roles that describe the structure of static, non-interactive content.
Self-contained composition independent of the rest of the page.
Group of non-interactive list items.
Heading for a section of the page. Use aria-level when not a native h1–h6.
Common states & properties
<div role="heading" aria-level="2">Section title</div>Container for one or more images that are intended to be combined into a single graphic.
Common states & properties
Removes the implicit semantics of an element (use sparingly).
<table role="presentation">Roles for single interactive controls.
A clickable element that performs an action.
Common states & properties
An interactive reference to a resource.
Common states & properties
Tri-state checkable input.
Common states & properties
A checkable input within a radiogroup.
Common states & properties
Two-state switchable control (on/off).
Common states & properties
<button role="switch" aria-checked="true">Wi-Fi</button>User input for a value within a range.
Common states & properties
Numeric input where the user can type or use up/down arrows.
Common states & properties
Single- or multi-line input that allows free-form text.
Common states & properties
Type of textbox intended for entering search criteria.
Element that displays the progress status of a task.
Common states & properties
Contextual popup describing an element.
Common states & properties
Roles that contain multiple focusable child widgets and require keyboard navigation patterns.
An offer of a list of common actions, often associated with a menu button.
Common states & properties
Set of layered sections of content (tabs) where only one is visible at a time.
Common states & properties
Composite widget combining a single-line input and a popup that lets the user choose a value.
Common states & properties
Hierarchically organized list, like a file system.
Common states & properties
Composite widget containing tabular data with full keyboard navigation.
Common states & properties
Roles for application-window-style overlays — usually with focus trapping and modal semantics.
Application window separated from the main content. Requires focus management.
Common states & properties
<div role="dialog" aria-modal="true" aria-labelledby="t1">…</div>Dialog containing an alert message that requires user response.
Common states & properties
Roles whose content changes dynamically and should be announced to assistive technology.
Important, time-sensitive information. Implicit aria-live=assertive.
<div role="alert">Saved.</div>Advisory information that does not require user action. Implicit aria-live=polite.
Live region for chat-style updates where new entries are appended.
Non-essential, scrolling info (think stock tickers).
Numerical countdown or count-up timer.
Attributes that work across many roles. States change as the user interacts; properties are usually fixed for the lifetime of the element.
| Attribute | Kind | Applies to | Description | Values |
|---|---|---|---|---|
| aria-label | property | Most roles missing a visible label | Defines a string value that labels the current element. | string |
| aria-labelledby | property | Most roles | IDs of elements that label the current element. Wins over aria-label. | ID reference list |
| aria-describedby | property | Most roles | IDs of elements that describe the current element (e.g., help text). | ID reference list |
| aria-hidden | state | Any element | Hides the element from the accessibility tree (and thus from screen readers). | true | false |
| aria-disabled | state | Most widgets | Marks an element as perceivable but disabled. Prefer the disabled HTML attribute when possible. | true | false |
| aria-current | state | Links, buttons | Marks the element representing the current item in a set. | page | step | location | date | time | true | false |
| aria-expanded | state | button, combobox, menuitem, etc. | Whether a control with a popup is open. | true | false | undefined |
| aria-pressed | state | button (toggle) | Indicates the current pressed state of a toggle button. | true | false | mixed | undefined |
| aria-selected | state | tab, option, treeitem, gridcell, row | Indicates the current selected state of selectable items. | true | false | undefined |
| aria-checked | state | checkbox, radio, switch, menuitemcheckbox | Indicates the current checked state. | true | false | mixed |
| aria-controls | property | tab, combobox, button (toggling content) | IDs of elements whose contents the current element controls. | ID reference list |
| aria-haspopup | property | button, menuitem, etc. | Indicates the type of popup the element triggers. | false | true | menu | listbox | tree | grid | dialog |
| aria-live | property | Live regions | Politeness with which assistive tech announces updates. | off | polite | assertive |
| aria-atomic | property | Live regions | Whether the entire region should be announced when any descendant changes. | true | false |
| aria-busy | state | Most roles | Element is being modified — defer announcements until false. | true | false |
| aria-required | property | form fields | User input is required before submission. Prefer the required HTML attribute. | true | false |
| aria-invalid | state | form fields | Entered value does not conform to expected format. | true | false | grammar | spelling |
| aria-readonly | property | form fields | User cannot modify the value, but it's still focusable. | true | false |
| aria-multiline | property | textbox | Whether the textbox accepts multi-line input. | true | false |
| aria-modal | property | dialog, alertdialog | Whether content outside the dialog is inert. | true | false |
| aria-orientation | property | scrollbar, slider, separator, tablist, toolbar, tree | Orientation of the element. | horizontal | vertical | undefined |
| aria-valuemin / valuemax / valuenow / valuetext | property | range widgets | Numeric range for sliders, progressbars, spinbuttons. | number / string |
| aria-keyshortcuts | property | Any focusable | Keyboard shortcut(s) the element will respond to. | string |
| aria-roledescription | property | Any element | Human-readable description of the element's role. Use sparingly. | string |