Skip to content
Tutorials Center
My learning

Topics

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.

HTML
<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

  1. 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.
  2. Don't change native semantics unless you really must. Write <h2><button>โ€ฆ</button></h2>, not <h2 role="button">.
  3. 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.
  4. Never hide a focusable element. Don't put role="presentation" or aria-hidden="true" on anything that can receive focus, or on a container of focusable elements.
  5. Every interactive element needs an accessible name. Visible text, a <label>, aria-labelledby or aria-label must 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

Disclosure button with aria-expanded

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>.

Live region with role=status

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.

Naming and describing controls

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.