HTML Reference ยท Attributes and Events
ARIA roles, states and properties
WAI-ARIA quick reference: the rules of ARIA use, landmark, widget, structure and live region roles, aria-* states and properties, and implicit roles of HTML elements.
WAI-ARIA (Accessible Rich Internet Applications) is a W3C specification that adds the role attribute and a family of aria-* attributes to HTML. They change what assistive technology such as a screen reader is told about an element: what it is (role), what it is called (name), and what state it is in (expanded, checked, invalidโฆ). This page follows WAI-ARIA 1.2, with a few newer 1.3 additions labeled as such.
<button aria-expanded="false" aria-controls="menu">Options</button>
ARIA changes only the accessibility tree. It adds no behavior: role="button" doesn't make an element focusable or clickable with the keyboard, and aria-disabled="true" doesn't block clicks. Your HTML and JavaScript must provide all of that.
The rules of ARIA use
- Use native HTML first. If an element with the meaning and behavior you need exists (
<button>,<nav>,<input type="checkbox">,<dialog>,<details>), use it instead of a<div>with a role. - Don't change native semantics unless you really must. Write
<h2><button>โฆ</button></h2>, not<h2 role="button">. - Every interactive ARIA control must work with the keyboard. A custom slider needs arrow keys, a custom button needs Enter and Space, and so on.
- Never hide a focusable element. Don't put
role="presentation"oraria-hidden="true"on anything that can receive focus, or on a container of focusable elements. - Every interactive element needs an accessible name. Visible text, a
<label>,aria-labelledbyoraria-labelmust give it one.
A short corollary: no ARIA is better than bad ARIA. Incorrect roles and stale states mislead users more than missing ones.
Landmark roles
Landmarks let screen reader users jump between the main regions of a page. Most of them come for free from HTML elements.
| Role | Meaning | HTML equivalent |
|---|---|---|
banner |
Site-wide header with the logo and main navigation. | <header> not inside a sectioning element or <main> |
complementary |
Supporting content related to the main content. | <aside> |
contentinfo |
Site-wide footer: copyright, legal links, contact. | <footer> not inside a sectioning element or <main> |
form |
A region containing a form. Only a landmark when it has an accessible name. | <form> with a name |
main |
The page's primary content. One per page. | <main> |
navigation |
A group of major navigation links. | <nav> |
region |
An important section a user may want to jump to. Requires an accessible name. | <section> with a name |
search |
The site or page search area. | <search> |
When a page has more than one landmark of the same type (two <nav>s), give each a distinct name with aria-label or aria-labelledby, such as "Primary" and "Footer".
Widget roles
Widgets are interactive controls. Using one of these roles commits you to implementing its keyboard behavior and keeping its states up to date.
Standalone widgets
| Role | Use for | Key states and properties | HTML equivalent |
|---|---|---|---|
button |
An action trigger. | aria-pressed (toggle button), aria-expanded, aria-haspopup |
<button> |
checkbox |
A checkable option. | aria-checked (true, false, mixed) |
<input type="checkbox"> |
link |
A navigation to another resource. | aria-current |
<a href> |
menuitem |
An action in a menu or menubar. |
aria-haspopup, aria-expanded |
none |
menuitemcheckbox |
A checkable item in a menu. | aria-checked |
none |
menuitemradio |
One of a group of exclusive items in a menu. | aria-checked |
none |
option |
A selectable item in a listbox. |
aria-selected, aria-checked |
<option> |
progressbar |
Progress of a long task. | aria-valuenow, aria-valuemin, aria-valuemax, aria-valuetext |
<progress> |
radio |
One choice in a group where only one can be checked. | aria-checked |
<input type="radio"> |
scrollbar |
A custom scroll control. | aria-controls, aria-valuenow, aria-orientation |
none |
searchbox |
A text field for search queries. | aria-placeholder, aria-autocomplete |
<input type="search"> |
separator |
A divider; when focusable, a splitter the user can move. | aria-valuenow, aria-orientation |
<hr> (non-focusable) |
slider |
Picking a value from a range. | aria-valuenow, aria-valuemin, aria-valuemax, aria-valuetext, aria-orientation |
<input type="range"> |
spinbutton |
A number with step up/down controls. | aria-valuenow, aria-valuemin, aria-valuemax, aria-required |
<input type="number"> |
switch |
An on/off toggle. | aria-checked (true or false) |
<input type="checkbox"> styled as a switch |
tab |
A tab in a tablist. |
aria-selected, aria-controls |
none |
tabpanel |
The content area shown by a tab. | aria-labelledby (pointing at its tab) |
none |
textbox |
Free-form text input. | aria-multiline, aria-placeholder, aria-readonly, aria-required |
<input type="text">, <textarea> |
treeitem |
An item in a tree. |
aria-expanded, aria-selected, aria-level |
none |
Composite widgets
These contain other widgets and usually manage focus among them, with one Tab stop for the whole group and arrow keys inside it.
| Role | Contains | Notes |
|---|---|---|
combobox |
A text field or button plus a popup listbox, grid, tree or dialog |
Needs aria-expanded and aria-controls; often aria-activedescendant and aria-autocomplete. HTML: <select>, or <input list> with a <datalist>. |
grid |
rows of gridcells |
An interactive table navigated with arrow keys, like a spreadsheet or calendar. |
listbox |
options |
Supports aria-multiselectable. HTML: <select multiple>. |
menu |
menuitem, menuitemcheckbox, menuitemradio |
For application-style command menus, not for site navigation links (use <nav> and a list). |
menubar |
menuitems |
A horizontal, persistent menu, like a desktop app's menu bar. |
radiogroup |
radios |
HTML: radio inputs sharing a name inside a <fieldset>. |
tablist |
tabs |
Supports aria-orientation. |
tree |
treeitems, optionally in groups |
A hierarchical list, like a file browser. |
treegrid |
rows that can expand |
A grid whose rows can be expanded and collapsed. |
Document structure roles
These describe non-interactive content. Almost all of them map to an HTML element, which you should use instead.
| Role | Meaning | HTML equivalent |
|---|---|---|
application |
A region where the page takes over all keyboard handling. Rarely appropriate. | none |
article |
A self-contained composition. | <article> |
blockquote |
A quotation from another source. | <blockquote> |
caption |
The caption of a table, grid or figure. | <caption>, <figcaption> |
cell |
A cell in a non-interactive table. | <td> |
code |
A fragment of computer code. | <code> |
columnheader |
A header cell for a column. | <th scope="col"> |
definition |
The definition of a term. | <dd> |
deletion / insertion |
Removed or added content. | <del>, <ins> |
document |
Content to read rather than operate, inside an application. |
none |
emphasis / strong |
Stressed or important text. | <em>, <strong> |
feed |
A scrollable list of articles that loads more as you scroll. |
none |
figure |
A figure, such as an image or diagram with a caption. | <figure> |
generic |
A container with no meaning of its own. Don't set it by hand. | <div>, <span> |
group |
A set of related items that isn't a landmark. | <fieldset>, <details>, <optgroup> |
heading |
A section heading. Use aria-level for its level. |
<h1>โ<h6> |
img |
A single image, possibly built from several elements (such as an inline SVG). Needs a name. | <img alt="โฆ"> |
list / listitem |
A list and its items. | <ul>, <ol>, <menu>, <li> |
math |
A mathematical expression. | <math> |
meter |
A scalar value within a known range (not progress). | <meter> |
none / presentation |
Removes the element's semantics; its content stays. | <img alt=""> |
note |
A parenthetical remark or aside to the main content. | none |
paragraph |
A paragraph. | <p> |
row / rowgroup |
A table row, and a group of rows. | <tr>; <thead>, <tbody>, <tfoot> |
rowheader |
A header cell for a row. | <th scope="row"> |
subscript / superscript |
Subscript and superscript text. | <sub>, <sup> |
table |
A non-interactive data table. | <table> |
term |
A term being defined. | <dt>, <dfn> |
time |
A date or time. | <time> |
toolbar |
A set of controls, such as formatting buttons. Arrow keys move between them. | none |
tooltip |
A popup describing an element, referenced with aria-describedby. |
none (see the popover="hint" global attribute) |
Live region roles
Live regions make screen readers announce content that changes without the user moving focus to it. The region must already be in the page before its content changes; inserting a new element that already contains the message is often not announced.
| Role | Implicit aria-live |
Use for |
|---|---|---|
alert |
assertive |
Important, time-sensitive messages, such as "Your session expires in 1 minute". Interrupts the user. |
log |
polite |
A stream where new entries are added in order: chat, history, console. |
marquee |
off |
Non-essential, frequently changing information such as a news ticker. |
status |
polite |
Advisory status that doesn't need immediate attention: "Saved", "3 results". HTML: <output>. |
timer |
off |
A counter of elapsed or remaining time. |
Window roles
| Role | Use for | HTML equivalent |
|---|---|---|
dialog |
A window that asks for input or shows information, separate from the page. Needs a name; add aria-modal="true" if it is modal. |
<dialog> |
alertdialog |
A dialog that interrupts with an urgent message and needs a response, such as "Delete this file?". | <dialog> with role="alertdialog" |
ARIA also defines abstract roles (command, composite, input, landmark, range, roletype, section, sectionhead, select, structure, widget, window). They organize the specification only; never use them in markup.
Global states and properties
These can be used on any element, whatever its role.
| Attribute | Values | Description |
|---|---|---|
aria-atomic |
true, false |
In a live region: announce the whole region (true) or only the changed nodes (false). |
aria-busy |
true, false |
The element is being updated; assistive technology may wait until it is false before announcing. |
aria-controls |
ID list | The element(s) whose content or presence this element controls. |
aria-current |
page, step, location, date, time, true, false |
Marks the current item in a set, such as the link to the page you are on. |
aria-describedby |
ID list | Element(s) whose text gives a longer description, read after the name. |
aria-description |
String | ARIA 1.3. A description given directly as text. Prefer visible text with aria-describedby. |
aria-details |
ID list | Element(s) with extended details, such as a long description of a chart. |
aria-flowto |
ID list | An alternate reading order. Poorly supported. |
aria-hidden |
true, false |
Removes the element and its children from the accessibility tree. Never on focusable content. |
aria-keyshortcuts |
Key combinations | Documents keyboard shortcuts, such as Control+S. Doesn't create them. |
aria-label |
String | Gives the element an accessible name directly. Use when there is no visible text to point at. |
aria-labelledby |
ID list | Names the element with the text of other elements. Overrides aria-label and native labels. |
aria-live |
off, polite, assertive |
Makes the element a live region. polite waits for a pause; assertive interrupts. |
aria-owns |
ID list | Treats elements elsewhere in the DOM as children of this one. Use only when you can't fix the DOM order. |
aria-relevant |
additions, removals, text, all |
Which kinds of changes in a live region are announced. Default additions text. |
aria-roledescription |
String | A human-friendly description of the role, such as "slide". Use rarely; it replaces the role name users rely on. |
Widget states and properties
| Attribute | Values | Used on | Description |
|---|---|---|---|
aria-autocomplete |
none, inline, list, both |
combobox, searchbox, textbox |
Whether typing shows predictions inline, in a popup list, or both. |
aria-checked |
true, false, mixed |
checkbox, radio, switch, menuitemcheckbox, menuitemradio, option |
The checked state. mixed is for a checkbox that controls a partly-checked group. |
aria-disabled |
true, false |
Any widget | The element is visible but not usable. Unlike disabled, it stays focusable and you must block activation yourself. |
aria-errormessage |
ID | Widgets with aria-invalid |
The element containing the error message, read when aria-invalid="true". |
aria-expanded |
true, false |
button, combobox, link, treeitem, row and others |
Whether the content it controls is expanded. Leave it off entirely if the element doesn't expand anything. |
aria-haspopup |
false, true (= menu), menu, listbox, tree, grid, dialog |
button, combobox, menuitem, link |
The element opens a popup of that type. |
aria-invalid |
false, true, grammar, spelling |
Form widgets | The value fails validation. Set it after the user tries to submit or leaves the field, not before. |
aria-level |
Integer โฅ 1 | heading, treeitem, row, listitem |
The hierarchical level. |
aria-modal |
true, false |
dialog, alertdialog |
The dialog is modal: content outside it is unavailable. |
aria-multiline |
true, false |
textbox |
Enter inserts a new line instead of submitting. |
aria-multiselectable |
true, false |
listbox, grid, tablist, tree |
More than one item can be selected. |
aria-orientation |
horizontal, vertical |
slider, scrollbar, separator, tablist, listbox, menu, toolbar and others |
The direction, which also tells users which arrow keys to use. |
aria-placeholder |
String | textbox, searchbox |
A hint shown while the field is empty. Native inputs use placeholder. |
aria-pressed |
true, false, mixed |
button |
Makes a button a toggle button and gives its state. Don't change the label too. |
aria-readonly |
true, false |
textbox, checkbox, grid, slider and others |
The value can be read but not changed. |
aria-required |
true, false |
Form widgets | The field must be filled before submitting. Native fields use required. |
aria-selected |
true, false |
tab, option, gridcell, row, treeitem |
Whether the item is selected. |
aria-sort |
ascending, descending, none, other |
columnheader, rowheader |
How the table is currently sorted by this column or row. Put it on one header at a time. |
aria-valuemax / aria-valuemin |
Number | slider, spinbutton, progressbar, scrollbar, meter, separator |
The range's limits. |
aria-valuenow |
Number | Same as above | The current value. Omit it on an indeterminate progress bar. |
aria-valuetext |
String | Same as above | A readable version of the value, such as "Medium" or "3 of 10 steps". |
Relationship and structure properties
| Attribute | Values | Description |
|---|---|---|
aria-activedescendant |
ID | On a composite widget that keeps DOM focus: which descendant is the active one (for example the highlighted option of a combobox). |
aria-colcount / aria-rowcount |
Integer (-1 if unknown) |
The total number of columns or rows when only some are in the DOM. |
aria-colindex / aria-rowindex |
Integer โฅ 1 | The position of a cell or row within the full table. |
aria-colspan / aria-rowspan |
Integer | How many columns or rows a cell spans, for ARIA grids and tables (native tables use colspan and rowspan). |
aria-posinset / aria-setsize |
Integer (setsize can be -1) |
An item's position in its set and the size of the set, when not all items are in the DOM. |
Deprecated: aria-grabbed and aria-dropeffect (old drag-and-drop states) are deprecated in ARIA 1.1 and later. Don't use them.
Implicit roles of HTML elements
Every element below already has the listed role, so don't repeat it (<nav role="navigation"> is redundant).
| HTML | Implicit role |
|---|---|
<a href>, <area href> |
link |
<a> without href |
generic |
<article> |
article |
<aside> |
complementary |
<blockquote> |
blockquote |
<button> |
button |
<code> |
code |
<datalist> |
listbox |
<dd> / <dt> |
definition / term |
<del> / <ins> |
deletion / insertion |
<details> |
group |
<dialog> |
dialog |
<div>, <span> |
generic |
<em> / <strong> |
emphasis / strong |
<fieldset> |
group |
<figure> |
figure |
<footer> |
contentinfo at page level; generic inside <article>, <aside>, <main>, <nav> or <section> |
<form> |
form (a landmark only when it has an accessible name) |
<h1>โ<h6> |
heading with aria-level 1โ6 |
<header> |
banner at page level; generic inside <article>, <aside>, <main>, <nav> or <section> |
<hr> |
separator |
<img alt="text"> |
img |
<img alt=""> |
presentation |
<input type="button">, submit, reset, image |
button |
<input type="checkbox"> |
checkbox |
<input type="radio"> |
radio |
<input type="range"> |
slider |
<input type="number"> |
spinbutton |
<input type="search"> (no list) |
searchbox |
<input type="text">, email, tel, url (no list) |
textbox |
<input> text-like type with list |
combobox |
<li> |
listitem |
<main> |
main |
<math> |
math |
<menu>, <ol>, <ul> |
list |
<meter> |
meter |
<nav> |
navigation |
<optgroup> |
group |
<option> |
option |
<output> |
status |
<p> |
paragraph |
<progress> |
progressbar |
<search> |
search |
<section> |
region when it has an accessible name, otherwise generic |
<select> (no multiple, no size > 1) |
combobox |
<select multiple> or size > 1 |
listbox |
<sub> / <sup> |
subscript / superscript |
<table> |
table |
<tbody>, <thead>, <tfoot> |
rowgroup |
<td> |
cell (gridcell inside a grid) |
<textarea> |
textbox (multi-line) |
<th> |
columnheader or rowheader |
<time> |
time |
<tr> |
row |
Some elements have no role and get no ARIA semantics of their own, for example <label>, <legend>, <summary> (browsers expose it as a disclosure control), <abbr>, <kbd> and <head> contents such as <meta> and <script>.
Examples
A native <button> brings focus and keyboard support; ARIA only adds the "expanded / collapsed" state. Styling from the aria-expanded attribute keeps the visual and announced states in sync. For a no-script version, use <details>.
Both paragraphs exist, empty, when the page loads, so updates to their text are announced: politely for the status message, immediately for the alert. Turn on a screen reader (VoiceOver, NVDA or Narrator) to hear the difference.
The icon button gets its name from aria-label, the <section> becomes a named region landmark through aria-labelledby, and the field is announced with its label, hint and error message.
Related
- Global attributes โ
hidden,inert,tabindexand other attributes that affect accessibility - All attributes โ AโZ list of HTML attributes
- Event attributes โ handling keyboard and pointer input for custom widgets
- Lessons: ARIA Roles, States and Properties, Accessibility Basics, Keyboard Access and Focus, Semantic Elements, Accessible Tables