Revision:
.. is a set of roles and attributes that define ways to make web content and web applications (especially those developed with JavaScript) more accessible to people with disabilities.
ARIA is not a true programming language but a set of attributes you can add to HTML elements to increase their accessibility. These attributes communicate role, state, and property to assistive technologies (AT) (e.g. screen readers) using accessibility APIs found in modern browsers. This communication happens through the accessibility tree.
ARIA modifies incorrect or incomplete code to create a better experience for those using AT by changing, exposing, and augmenting parts of the accessibility tree.
The accessibility tree is created by the browser and based on the standard Document Object Model (DOM) tree. Like the DOM tree, the accessibility tree contains objects representing all the markup elements, attributes, and text nodes.
The accessibility tree is also used by platform-specific accessibility APIs to provide a representation that assistive technologies can understand.
ARIA on its own doesn't change an element's functionality or visual appearance. That means only AT users will notice differences between a digital product with ARIA and one without it.
That also means that developers alone are responsible for making the appropriate code and styling changes to make an element as accessible as possible.
roles : define what an element is or does on the page or app.
<div role="button">Self-destruct</div>
properties : express characteristics or relationships to an object.
<div role="button" aria-describedby="more-info">Self-destruct</div>
<div id="more-info">This page will self-destruct in 10 seconds.</div>
states/values : define the current conditions or data values associated with the element.
<div role="button" aria-describedby="more-info" aria-pressed="false">Self-destruct</div>
<div id="more-info">This page will self-destruct in 10 seconds.</div>
P.S. While all three elements of ARIA can be used in one line of code, it's not required. Instead, layer ARIA roles, properties, and states or values until you've accomplished your final accessibility goal.
Correctly incorporating ARIA into your codebase ensures that AT users will have all the information they need to use your website, app, or other digital product successfully and equitably.
When the browser supports an HTML tag with an implicit role with an ARIA equivalent, there is usually no need to add ARIA to the element. However, ARIA still includes many roles, states, and properties that aren't available in any version of HTML. Those attributes remain useful for now.
If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so.
Don't: assign a role <a role="button">Submit</a>
Do: use the semantic element <button>Submit</button>
In most circumstances, HTML elements work well as-is and don't need additional ARIA added to them. In fact, developers using ARIA often have to add additional code to make the elements functional in the case of interactive elements.
Don't: assign a misleading role <h2 role="tab">Heading tab</h2>
Do: assign roles correctly <div role="tab"><h2>Heading tab<h2></div>
All interactive (not disabled) ARIA controls must be keyboard accessible. You can add tabindex= "0" to any element that needs a focus that doesn't normally receive keyboard focus. Avoid using tab indexes with positive integers whenever possible to prevent potential keyboard focus order issues.
Don't: add a tabindex <span role="button" tabindex="1">Submit</span>
Do: set the tabindex to '0' <span role="button" tabindex="0"><>Submit</span>
Don't add role= "presentation" or aria-hidden= "true" to elements that need to have focus — including elements with a tabindex= "0". When you add these roles and states to elements, it sends a message to the AT that these elements are not important and to skip over them. This can lead to confusion or disrupt users attempting to interact with an element.
Don't: hide focusable elements <div ariad-hidden="true"><button>Submit</button></div>
Do: expose focusable elements <div><button>Submit</button></div>
The purpose of an interactive element needs to be conveyed to a user before they know how to interact with it. Ensure that all elements have an accessible name for people using AT devices.
Accessible names can be the content surrounded by an element (in the case of an <a>), alternative text, or a label.
There are many ways to check an element's accessible name, including inspecting the accessibility tree using Chrome DevTools or testing it with a screen reader.
While using HTML elements on their own is best practice, ARIA elements can be added in certain situations.
For example, you may pair ARIA with HTML in patterns that need a higher level of AT support because of environmental constraints or as a fall-back method for HTML elements that aren't fully supported by all browsers.
Of course, there are recommendations for implementing ARIA in HTML.
Most importantly: don't override default HTML roles, reduce redundancy, and be aware of unintended side effects.
ARIA attributes enable modifying an element's states and properties as defined in the accessibility tree.
There are 4 categories of ARIA states and properties:
indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions will be presented if they are made.
values:
none (default): When a user is providing input, no automatic suggestion is displayed.
inline : text suggesting one way to complete the provided input may be dynamically inserted after the caret.
list : when a user is providing input, an element containing a collection of values that could complete the provided input may be displayed.
both : an input to offer both models at the same time. When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. If displayed, one value in the collection is automatically selected, and the text needed to complete the automatically selected value appears after the caret in the input.
associated roles : combobox, textbox, searchbox
indicates the current "checked" state of checkboxes, radio buttons, and other widgets.
values:
false : the element supports being checked but is not currently checked.
true : the element is checked.
mixed : for checkbox and menuitemcheckbox only, equivalent to indeterminate, indicating a mixed mode value of neither checked nor unchecked.
undefined (default): the element does not support being checked.
used in roles : checkbox, menuitemcheckbox, menuitemradio, option, radio, switch
example
<span role="checkbox" id="checkBoxInput" aria-checked="false" tabindex="0" aria-labelledby="chk15-label"></span>
<label id="chk15-label">Subscribe to the newsletter</label>
indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.
values:
true : the element is disabled
false : the element is not disabled
used in roles : application, button, composite, gridcell, group, input, link, menuitem, scrollbar, separator, tab
inherits into roles: checkbox, columnheader, combobox, grid, listbox, menu, menubar, menuitemcheckbox, menuitemradio, option, radio, radiogroup, row, rowheader, searchbox, select, slider, spinbutton, switch, tablist, textbox, toolbar, tree, treegrid, treeitem
identifies the element that provides an error message for that object.
values:
id : the value of the "id" of the element containing the error message for the current element
used in roles: application, checkbox, combobox, gridcell, listbox, radiogroup, slider, spinbutton, textbox, tree
inherits from roles: columnheader, rowheader, searchbox, switch, treegrid
used in roles: application, button, checkbox, combobox, gridcell, link, listbox, menuitem, row, rowheader, tab, treeitem
inherits into roles: columnheader, menuitemcheckbox, menuitemradio, rowheader, switch
is set on an element to indicate if a control is expanded or collapsed, and whether or not the controlled elements are displayed or hidden.
values:
false : the grouping element this element owns or controls is collapsed.
true : the grouping element this element owns or controls is expanded.
udefined (default): the element does not own or control a grouping element that is expandable.
used in roles: application, button, checkbox, combobox, gridcell, link, listbox, menuitem, row, rowheader, tab, treeitem
inherits into roles: columnheader, menuitemcheckbox, menuitemradio, rowheader, switch
indicates the availability and type of interactive popup element that can be triggered by the element on which the attribute is set.
values:
false : (default) the element does not have a popup.
true : the popup is a menu.
menu : the popup is a menu.
listbox : the popup is a listbox.
tree : the popup is a tree.
grid : the popup is a grid.
dialog : the popup is a dialog.
used in roles: application, button, combobox, gridcell, link, menuitem, slider, tab, textbox, treeitem
inherited into roles: columnheader, menuitemcheckbox, menuitemradio, rowheader, searchbox
indicates whether the element is exposed to an accessibility API.
values:
false : the element is exposed to the accessibility API as if it was rendered.
true : the element is hidden from the accessibility API.
udefined : (default) the element's hidden state is determined by the user agent based on whether it is rendered.
used in ALL roles
indicates the entered value does not conform to the format expected by the application.
values:
grammar : a grammatical error was detected.
false (default) : there are no detected errors in the value.
spelling : a spelling error was detected.
true : the value entered by the user has failed validation.
used in roles: application, checkbox, combobox, gridcell, listbox, radiogroup, slider, spinbutton, textbox, tree
inherited into roles: columnheader, rowheader, searchbox, switch, treegrid
defines a string value that can be used to name an element, as long as the element's role does not prohibit naming.
values:
string : a string of text that will be the accessible name for the object.
used in almost all roles except roles that cannot be provided an accessible name by the author.
The aria-label attribute is NOT supported in: code, caption, definition, deletion, emphasis, generic, insertion, mark, paragraph, presentation / none , strong, subscript, superscript, suggestion, term, time
defines the hierarchical level of an element within a structure.
values:
integer : an integer greater than or equal to 1.
used in roles: associationlistitemkey, comment, heading, row
indicates whether an element is modal when displayed.
values:
false (default) : element is not modal.
true : element is modal.
used in roles: window
inherits into roles: alertdialog, dialog
indicates whether a textbox accepts multiple lines of input or only a single line.
values:
true : the text box accepts multiple lines of input.
false : the text box only accepts a single line of input.
used in roles: textbox
inherits into roles: searchbox
indicates that the user may select more than one item from the current selectable descendants.
values:
true : more than one item in the widget may be selected at a time
false : only one item can be selected
used in roles: grid, listbox, tablist, tree
inherited into roles: treegrid
indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous.
values:
horizontal : the element is oriented horizontally.
undefined (default) : the element's orientation is unknown/ambiguous.
vertical : the element is oriented vertically.
used in roles: scrollbar, select, separator, slider, tablist, toolbar
inherited into roles: listbox, menu, menubar, radiogroup, tree, treegrid
defines a short hint (a word or short phrase) intended to help the user with data entry when a form control has no value. The hint can be a sample value or a brief description of the expected format.
values:
string : the word or short phrase to display in a control when the control has no value.
used in roles: textbox
inherited into roles: searchbox
indicates the current "pressed" state of a toggle button.
values:
false : the button supports being pressed but is not currently pressed.
mixed : indicates a mixed mode value for a tri-state toggle button.
true : the button is pressed.
undefined : the element does not support being pressed.
used in roles: button
indicates that the element is not editable, but is otherwise operable
values:
true : the element is readonly.
false (default): the element is not readonly.
used in roles: checkbox, combobox, grid, gridcell, listbox, radiogroup, slider, spinbutton, textbox
inherited into roles: columnheader, rowheader, searchbox, switch, treegrid
indicates that user input is required on the element before a form may be submitted.
values:
true : the element requires a value or must be checked for the form to be submittable.
false : the element is not required.
used in roles: checkbox, combobox, gridcell, listbox, radiogroup, spinbutton, textbox, tree
inherits into roles: columnheader, rowheader, searchbox, switch, treegrid
indicates the current "selected" state of various widgets.
values:
true : the selectable element is selected.
false : the selectable element is not selected. Implicit default for "tab".
undefined (default): the element is not selectable.
used in roles: gridcell, option, row, tab
inherited into roles: columnheader, rowheader, treeitem
indicates if items in a table or grid are sorted in ascending or descending order.
values:
ascending : items are sorted in ascending order by this column.
descending : items are sorted in descending order by this column.
none (default): there is no defined sort applied to the column.
other : a sorting algorithm other than ascending or descending has been applied.
used in roles: columnheader, rowheader
defines the maximum allowed value for a range widget.
values:
number : an integer or decimal number that is greater than the minimum value.
used in roles: meter, scrollbar (required), separator, slider (required), spinbutton (required)
inherited into roles: meter, progressbar, scrollbar, slider, spinbutton
defines the minimum allowed value for a range widget.
values:
number : a decimal number, below the maximum value.
used in roles: meter, scrollbar, separator, slider, spinbutton
inherited into roles: meter, progressbar, scrollbar, slider, spinbutton
defines the current value for a "range" widget.
values:
number : a decimal number, between the minimum and maximum values.
used in roles: meter, scrollbar, separator, slider, spinbutton
inherited into roles: meter, progressbar, scrollbar, slider, spinbutton
defines the human-readable text alternative of aria-valuenow for a range widget.
values:
string : a human-readable text alternative of the aria-valuenow value.
used in roles: range, separator, spinbutton
inherited into roles: meter, progressbar, scrollbar, slider, spinbutton
indicates an element is being modified and that assistive technologies may want to wait until the changes are complete before informing the user about the update.
values :
false (default): there are no expected updates for the element.
true : the element is being updated.
used in ALL roles
indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.
values :
assertive : indicates that updates to the region have the highest priority and should be presented to the user immediately.
off (default): indicates that updates to the region should not be presented to the user unless the user is currently focused on that region.
polite : indicates that updates to the region should be presented at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses typing.
used in ALL roles
indicates what notifications the user agent will trigger when the "accessibility tree" within a live region is modified.
values :
additions : element nodes are added to the accessibility tree within the live region.
all : shorthand for "additions" "removals" "text".
removals : text content, a text alternative, or an element node within the live region is removed from the accessibility tree.
text : text content or a text alternative is added to any descendant in the accessibility tree of the live region.
used in ALL roles
indicates whether assistive technologies such as a screen reader will present all, or only parts of, the changed region based on the change notifications defined by the "aria-relevant" attribute.
values :
false (default): present only the changed node or nodes.
true : present the entire changed region as a whole, including the author-defined label if one exists.
used in ALL roles
indicates what functions may be performed when a dragged object is released on the drop target - dprecated.
indicates an element's "grabbed" state in a drag-and-drop operation. - deprecated
identifies the currently active element when focus is on a "composite" widget, "combobox", "textbox", "group", or "application".
values :
ID reference : takes as its value the "id" of the currently focused element.
relevant only as an attribute on elements with the following roles: application, combobox, composite, group, textbox
defines the total number of columns in a "table", "grid", or "treegrid" when not all columns are present in the DOM.
values :
integer : the number of columns in the full table
used in roles: <table>
inherits into roles: grid, treegrid
defines an element's column index or position with respect to the total number of columns within a "table", "grid", or "treegrid".
values :
integer : integer greater than or equal to 1 and less than or equal to the total number of columns if all were present.
used in roles: cell, row
inherits into roles: columnheader, gridcell, rowheader
defines the number of columns spanned by a cell or gridcell within a "table", "grid", or "treegrid".
values :
integer : an integer greater than or equal to the default value of 1 defining the number of columns spanned by the cell. The value must be less than what would cause a cell to overlap the next cell in the same row.
used in roles: cell
inherits into roles: columnheader, rowheader
identifies the element (or elements) whose contents or presence are controlled by the element on which this attribute is set.
values :
"id" list : a space-separated list of one or more ID values referencing the elements being controlled by the current element
used in ALL roles.
identifies the element (or elements) that describes the element on which the attribute is set.
values :
ID reference list : The "id" or space-separated "list" of element ids that describe the current element.
used in all roles. Usable in all HTML elements as well.
defines a string value that describes or annotates the current element.
values :
string : the value is a string, an unconstrained value type, that is intended to be conveyed to the assistive technology user.
used in ALL roles.
identifies the element (or elements) that provide additional information related to the object.
values :
ID reference list : The "id" or space-separated "list" of element ids that describe the current element.
used in ALL roles.
identifies the element that provides an error message for that object.
values :
"id" reference : the value of the id of the element containing the error message for the current element
used in roles: application, checkbox, combobox, gridcell, listbox, radiogroup, slider, spinbutton, textbox, tree
inherits from roles: columnheader, rowheader, searchbox, switch, treegrid
identifies the next element (or elements) in an alternate reading order of content. This allows assistive technology to override the general default of reading in document source order at the user's discretion.
values :
id : suggested next element in the reading order.
"id" list : space separated list of ID values referencing the suggested elements the user may want to go to next in the alternate reading order of content.
used in ALL roles.
identifies the element (or elements) that labels the element it is applied to.
values :
ID reference list : The "id" or space-separated "list" of element ids that describe the current element.
used in almost all roles except roles that can not be provided an accessible name by the author.
The aria-labelledby attribute is NOT supported in: code, caption, deletion, emphasis, generic, insertion, mark, paragraph, presentation / none, strong, subscript, superscript, suggestion, term, time
identifies an element (or elements) in order to define a visual, functional, or contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used to represent the relationship.
values :
'id' list : Space separated list of one or more ID values referencing the elements being owned by the current element
used in ALL roles.
defines an element's number or position in the current set of listitems or treeitems when not all items are present in the DOM.
values :
integer : integer greater than or equal to 1, and less than or equal to the value of aria-setsize.
used in roles: article, associationlistitemkey, associationlistitemvalue, comment, listitem, menuitem, option, radio, row, tab
inherits into roles: comment, menuitemcheckbox, menuitemradio, treeitem
defines the total number of rows in a "table", "grid", or "treegrid".
values :
integer : the number of rows in the full table or -1 if the table size is not known.
used in roles: table
inherited into roles: grid, treegrid
defines an element's position with respect to the total number of rows within a "table", "grid", or "treegrid".
values :
integer : an integer greater than or equal to 1, greater than the aria-rowindex of the previous row, if any, and less than or equal to the value of aria-rowcount.
used in roles: cell, row
inherited into roles: columnheader, gridcell, rowheader
defines the number of rows spanned by a cell or gridcell within a "table", "grid", or "treegrid".
values :
integer : an integer greater than or equal to 0 and less than would cause a cell to overlap the next cell in the same column.
used in roles: cell
inherited into roles: columnheader, rowheader
defines the number of items in the current set of listitems or treeitems when not all items in the set are present in the DOM.
values :
integer : The number of items in the full set or -1 if the set size is unknown.
used in roles: article, associationlistitemkey, associationlistitemvalue, comment, listitem, menuitem, option, radio, row, tab
inherits into roles: comment, menuitemcheckbox, menuitemradio, treeitem
ARIA roles provide semantic meaning to content, allowing screen readers and other tools to present and support interaction with an object in a way that is consistent with user expectations of that type of object. ARIA roles can be used to describe elements that don't natively exist in HTML or exist but don't yet have full browser support.
There are 6 categories of ARIA roles:
These are used to provide a structural description for a section of content. Most of these roles should no longer be used as browsers now support semantic HTML elements with the same meaning.
The roles without HTML equivalents, such as presentation, toolbar and tooltip roles, provide information on the document structure to assistive technologies such as screen readers, as equivalent native HTML tags are not available.
defines the containing element as a collection of commonly used function buttons or controls represented in a compact visual form.
is a contextual text bubble that displays a description for an element that appears on pointer hover or keyboard focus.
is a dynamic scrollable list of articles in which articles are added to or removed from either end of the list as the user scrolls. A feed enables screen readers to use the browse mode reading cursor to both read and scroll through a stream of rich content that may continue scrolling infinitely by loading more content as the user reads.
indicates that the content represents a mathematical expression.
remove an element's implicit ARIA semantics from being exposed to the accessibility tree.
The content of the element will still be available to assistive technologies; it is only the semantics of the container — and in some instance, required associated descendants — which will no longer expose their mappings to the accessibility API.
suggests a section whose content is parenthetic or ancillary to the main content.
For most document structure roles, semantic HTML equivalent elements are available and supported. Avoid using:
application
article (use <article>)
cell (use <td>)
columnheader (use <th scope="col">)
definition (use <dfn>)
directory
document
figure (use <figure> instead)
group
heading (use h1 through h6)
img (use <img> or <picture> instead)
list (use either <ul> or <ol> instead)
listitem (use <li> instead)
meter (use <meter> instead)
row (use the <tr> with <table>)
rowgroup (use <thead>, <tfoot> and <tbody>)
rowheader (use <th scope="row">)
separator (use <hr> if it doesn't have focus)
table (use <table>)
term (use <dfn>)
Widget roles are used to define common interactive patterns. Like document structure roles, some widget roles have the same semantics as well-supported native HTML elements, and therefore should be avoided.
The key difference is that widget roles typically require JavaScript for interaction, while document structure roles often do not.
is a graphical object that controls the scrolling of content within a viewing area.
indicates an element is a type of textbox intended for specifying search criteria.
indicates the element is a divider that separates and distinguishes sections of content or groups of menuitems. The implicit ARIA role of the native thematic break <hr> element is separator.
defines an input where the user selects a value from within a given range.
defines a type of range that expects the user to select a value from among discrete choices.
is functionally identical to the checkbox role, except that instead of representing "checked" and "unchecked" states, which are fairly generic in meaning, the switch role represents the states "on" and "off."
indicates an interactive element inside a tablist that, when activated, displays its associated tabpanel.
is a container for the resources of layered content associated with a tab.
is an item in a "tree".
Avoid using button, checkbox, gridcell, link, menuitem, menuitemcheckbox, menuitemradio, option, progressbar, radio, and textbox. For most, semantic equivalents with accessible interactivity are available and supported.
composite widget roles
identifies an element as an input that controls another element, such as a listbox or grid, that can dynamically pop up to help the user set the value of that input.
is a type of composite widget that offers a list of choices to the user.
is a presentation of menu that usually remains visible and is usually presented horizontally.
identifies the element that serves as the container for a set of tabs. The tab content are referred to as tabpanel elements.
is a widget that allows the user to select one or more items from a hierarchically organized collection.
identifies an element as being grid whose rows can be expanded and collapsed in the same manner as for a tree.
Avoid using grid, listbox, and radiogroup.
Landmark roles provide a way to identify the organization and structure of a web page. By classifying and labeling sections of a page, structural information conveyed visually through layout is represented programmatically.
Screen readers use landmark roles to provide keyboard navigation to important sections of a page. Use these sparingly. Too many landmark roles create "noise" in screen readers, making it difficult to understand the overall layout of the page.
is for defining a global site header, which usually includes a logo, company name, search feature, and possibly the global navigation or a slogan. It is generally located at the top of the page.
is used to designate a supporting section that relates to the main content, yet can stand alone when separated. These sections are frequently presented as sidebars or call-out boxes. If possible, use the HTML
defines a footer, containing identifying information such as copyright information, navigation links, and privacy statements, found on every document within a site. This section is commonly called a footer.
can be used to identify a group of elements on a page that provide equivalent functionality to an HTML form. The form is not exposed as a landmark region unless it has an accessible name.
is used to indicate the primary content of a document. The main content area consists of content that is directly related to or expands upon the central topic of a document, or the main function of an application.
is used to identify major groups of links used for navigating through a website or page content.
is used to identify document areas the author deems significant. It is a generic landmark available to aid in navigation when none of the other landmark roles are appropriate.
is used to identify the search functionality; the section of the page used to search the page, site, or collection of sites.
Live Region roles are used to define elements with content that will be dynamically changed. Sighted users can see dynamic changes when they are visually noticeable.
These roles help low vision and blind users know if content has been updated. Assistive technologies, like screen readers, can be made to announce dynamic content changes.
is for important, and usually time-sensitive, information. The alert is a type of status processed as an atomic live region.
example
<div class="form-errors" role="alert">
The alert will trigger when the content of this element changes.
</div>
is used to identify an element that creates a live region where new information is added in a meaningful order and old information may disappear.
is a type of live region containing non-essential information which changes frequently.
defines a live region containing advisory information for the user that is not important enough to be an alert.
indicates to assistive technologies that an element is a numerical counter listing the amount of elapsed time from a starting point or the remaining time until an end point. Assistive technologies will not announce updates to a timer as it has an implicit aria-live value of off.
Window roles define sub-windows to the main document window, within the same window, such as pop up modal dialogs.
is to be used on modal alert dialogs that interrupt a user's workflow to communicate an important message and require a response.
is used to mark up an HTML based application dialog or window that separates content or UI from the rest of the web application or page. Dialogs are generally placed on top of the rest of the page content using an overlay. Dialogs can be either non-modal (it's still possible to interact with content outside of the dialog) or modal (only the content in the dialog can be interacted with).
Abstract roles are only intended for use by browsers to help organize and streamline a document. They should not be used by developers writing HTML markup. Doing so will not result in any meaningful information being conveyed to assistive technologies or to users.
Avoid using command, composite, input, landmark, range, roletype, section, sectionhead, select, structure, widget,and window.