ARIA Reference
ARIA, or Accessible Rich Internet Applications, provides roles, states, and properties that can help communicate the purpose and behavior of web content to assistive technologies.
ARIA is especially useful for custom controls and dynamic interfaces when native HTML cannot provide the required accessibility information. Whenever possible, use the appropriate native HTML element before adding ARIA.
What is ARIA?
ARIA is a set of attributes that can describe the role, state, properties, and relationships of elements so assistive technologies can better understand an interface.
ARIA does not change how an element looks or automatically add keyboard behavior. When ARIA is used with a custom interactive control, the required interaction and keyboard behavior must still be implemented.
Use Native HTML First
Native HTML elements already provide built-in semantics, keyboard behavior, and accessibility features. A native <button>, for example, should normally be used instead of creating a button from a generic <div>.
<button type="button">Save Changes</button>Adding unnecessary ARIA can duplicate or conflict with the semantics already provided by HTML. Use ARIA when additional accessibility information is genuinely needed.
ARIA Roles
The role attribute identifies the purpose of an element. Roles are grouped into categories such as landmarks, widgets, document structure, and live regions.
<div role="alert">Your changes could not be saved.</div>Once a role is assigned, it should not be changed merely to alter the visual appearance of an element. The role should accurately describe the element's function.
Landmark Roles
Landmark roles identify major areas of a webpage and can help assistive technology users navigate between important sections.
| Role | Description |
|---|---|
banner | Identifies site-oriented content typically found at the beginning of a page. |
complementary | Identifies supporting content that is related to the main content. |
contentinfo | Identifies information about the page, such as copyright or footer information. |
form | Identifies a region containing a collection of items and controls that form a recognizable form. |
main | Identifies the primary content of the document. |
navigation | Identifies a collection of navigation links. |
region | Identifies an important section of content that users may want to navigate to. |
search | Identifies a region containing search functionality. |
Widget Roles
Widget roles describe interactive controls. Many have native HTML equivalents that should be used whenever they provide the required behavior.
| Role | Description |
|---|---|
button | Identifies an interactive control that performs an action when activated. |
checkbox | Identifies a checkable control with a checked, unchecked, or mixed state. |
combobox | Identifies an input control associated with another element, such as a listbox or grid, that can help users choose a value. |
link | Identifies an interactive reference to another resource or location. |
menuitem | Identifies an option contained in a menu or menubar. |
radio | Identifies a checkable option in a group where one option is normally selected. |
slider | Identifies an input where a value is selected from a range. |
switch | Identifies an on/off control. |
tab | Identifies a tab used to select an associated tab panel. |
textbox | Identifies an element that accepts text input. |
Document Structure Roles
Document structure roles describe the organization and meaning of content within a document or application.
| Role | Description |
|---|---|
article | Identifies a section of content that can stand independently within a document or page. |
cell | Identifies a cell within a row of a table or grid. |
heading | Identifies a heading for a section of content. |
list | Identifies a collection of list items. |
listitem | Identifies an item within a list. |
row | Identifies a row of cells within a table, grid, or treegrid. |
table | Identifies a non-interactive tabular structure containing rows and cells. |
toolbar | Identifies a collection of commonly used controls grouped together. |
Live Region Roles
Live region roles identify content that may change dynamically and may need to be announced by assistive technologies without requiring the user to move focus.
| Role | Description |
|---|---|
alert | Identifies important, usually time-sensitive information that should be communicated to the user. |
log | Identifies a region where new information is added in a meaningful order, such as a chat history. |
marquee | Identifies changing nonessential information that is not necessarily presented in a meaningful order. |
status | Identifies advisory information that is not important enough to justify an alert. |
timer | Identifies a numerical counter showing elapsed or remaining time. |
ARIA Properties
ARIA properties provide additional information about an element, including its label, description, relationships, and other characteristics.
| Property | Description |
|---|---|
aria-controls | Identifies the element or elements whose contents or presence are controlled by the current element. |
aria-describedby | Identifies elements that provide an accessible description for the current element. |
aria-description | Provides an accessible description directly as a string. |
aria-details | Identifies an element that provides additional detailed information about the current element. |
aria-label | Provides an accessible name directly as a string. |
aria-labelledby | Identifies one or more elements whose text provides the accessible name. |
aria-live | Indicates how updates to a live region should be communicated to assistive technologies. |
aria-owns | Identifies elements that should be treated as children of the current element in the accessibility tree when the DOM relationship cannot be used. |
aria-roledescription | Provides a human-readable description for the purpose of a role. |
ARIA States
ARIA states communicate information that may change as users interact with a control or interface.
| State | Description |
|---|---|
aria-busy | Indicates that an element is being updated and may not yet be complete. |
aria-checked | Indicates the checked state of a checkbox, radio button, or other supported control. |
aria-current | Indicates the current item within a related set of items. |
aria-disabled | Indicates that an element is perceivable but unavailable for interaction. |
aria-expanded | Indicates whether a controlled or owned element is expanded or collapsed. |
aria-hidden | Indicates whether an element is exposed to the accessibility API. |
aria-invalid | Indicates that an entered or selected value does not meet the expected requirements. |
aria-pressed | Indicates the pressed state of a toggle button. |
aria-selected | Indicates whether an item is selected. |
Accessible Names & Descriptions
An accessible name identifies an element to assistive technologies. Whenever possible, visible text or a native HTML <label> should provide the name. ARIA can provide or reference a name when the necessary information is not otherwise available.
<button type="button" aria-label="Close">X</button>The aria-labelledby attribute can reference visible text elsewhere on the page, while aria-describedby can associate additional descriptive information with an element.
<label for="password">Password</label>
<input type="password" id="password" aria-describedby="password-help">
<p id="password-help">Use at least 12 characters.</p>ARIA Example
ARIA can provide additional state information for an interactive control. In this example, aria-expanded communicates whether the content controlled by the button is currently expanded.
<button type="button"
aria-expanded="false"
aria-controls="details">
Show Details
</button>
<div id="details" hidden>
Additional information appears here.
</div>JavaScript would be needed to change the visibility of the content and keep the aria-expanded value synchronized with its actual state.
ARIA Best Practices
- Use native HTML elements whenever they provide the required semantics and behavior.
- Do not add ARIA when native HTML already communicates the same information correctly.
- Use roles that accurately describe an element's purpose.
- Use only ARIA states and properties that are supported by the element's role.
- Keep dynamic ARIA states synchronized with the actual state of the interface.
- Make custom interactive controls keyboard accessible.
- Provide accessible names for interactive controls when their purpose is not already communicated by visible text or native HTML.
- Do not use
aria-hidden="true"on content that users must be able to reach or understand through assistive technology. - Test interactive content with keyboard navigation and appropriate accessibility tools.