- Source MDN
- Widget roles
- Document structure roles
- Landmark roles
- Widget roles
- State and properties
- Potential Value Types
- Widget attributes
- aria-checked - (state)
- aria-current - (state)
- aria-disabled - (state)
- aria-expanded - (state)
- aria-hidden - (state)
- aria-invalid - (state)
- aria-pressed - (state)
- aria-selected - (state)
- Live region attributes
- Drag-and-Drop Attributes
- Relationship Attributes
ARIA allows developers to declare a semantic role for an element that otherwise offers incorrect or no semantics. For example, when an unordered list is used to create a menu, the
<ul> should be given a role of menubar and each
<li> should be given a role of menuitem.
The role of an element should not change. Instead, remove the original element and replace it with an element with the new role.
The following roles act as standalone user interface widgets or as part of larger, composite widgets.
A message with important, and usually time-sensitive, information. See related alertdialog and status.
A type of dialog that contains an alert message, where initial focus goes to an element within the dialog. See related alert and dialog.
An input that allows for user-triggered actions when clicked or pressed. See related link.
<button>, <input type="submit">, <input type="reset">, <input type="image">
A checkable input that has three possible values: true, false, or mixed
A dialog is an application window that is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response. See related alertdialog.
A cell in a grid or treegrid.
An interactive reference to an internal or external resource that, when activated, causes the user agent to navigate to that resource. See related button.
<a href...>, <area>
A type of live region where new information is added in meaningful order and old information may disappear. See related marquee.
Note: Elements with the role log have an implicit aria-live value of polite.
A type of live region where non-essential information changes frequently. See related log.
Note: Elements with the role marquee maintain the default aria-live value of off.
An option in a group of choices contained by a menu or menubar.
A checkable menuitem that has three possible values: true, false, or mixed.
A checkable menuitem in a group of menuitemradio roles, only one of which can be checked at a time.
A selectable item in a select list.
An element that displays the progress status for tasks that take a long time.
Note: Elements with the role progressbar have an implicit aria-readonly value of true.
A checkable input in a group of radio roles, only one of which can be checked at a time.
A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area.
Note: Elements with the role progressbar have an implicit aria-readonly value of true.
A user input where the user selects a value from within a given range.
A form of range that expects the user to select from among discrete choices.
HTML related: input element with a type attribute in the Number state
A container whose content is advisory information for the user but is not important enough to justify an alert, often but not necessarily presented as a status bar. See related alert.
Note: Elements with the role status have an implicit aria-live value of polite.
A grouping label providing a mechanism for selecting the tab content that is to be rendered to the user.
A container for the resources associated with a tab, where each tab is contained in a tablist.
nput that allows free-form text as its value.
<textarea>, <input type="text">(and other text-like inputs, such as 'password', 'email', etc.).
A type of live region containing a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point.
A contextual popup that displays a description for an element.
An option item of a tree. This is an element within a tree that may be expanded or collapsed if it contains a sub-level group of treeitems.
The following roles act as composite user interface widgets. These roles typically act as containers that manage other, contained widgets.
A presentation of a select; usually similar to a textbox where users can type ahead to select an option, or type to enter arbitrary text as a new item in the list. See related listbox.
<select>, HTML5 input types which provide suggestions
A grid is an interactive control which contains cells of tabular data arranged in rows and columns, like a table.
A widget that allows the user to select one or more items from a list of choices. See related combobox and list.
<select>, <datalist>(when aria-multiselectable set to false on listbox)
A type of widget that offers a list of choices to the user.
A presentation of menu that usually remains visible and is usually presented horizontally.
A group of radio buttons.
A list of tab elements, which are references to tabpanel elements.
A type of list that may contain sub-level nested groups that can be collapsed and expanded.
A grid whose rows can be expanded and collapsed in the same manner as for a tree.
Document structure roles
The following roles describe structures that organize content in a page. Document structures are not usually interactive.
A section of a page that consists of a composition that forms an independent part of a document, page, or site.
A cell containing header information for a column.
A definition of a term or concept.
A list of references to members of a group, such as a static table of contents.
A region containing related information that is declared as document content, as opposed to a web application.
A set of user interface objects which are not intended to be included in a page summary or table of contents by assistive technologies.
A heading for a section of the page.
<h1>, <h2>, etc.
Note: aria-level must be set appropriately
A container for a collection of elements that form an image.
A group of non-interactive list items. See related listbox.
A single item in a list or directory.
Content that represents a mathematical expression.
A section whose content is parenthetic or ancillary to the main content of the resource.
An element whose implicit native role semantics will not be mapped to the accessibility API.
A large perceivable section of a web page or document, that the author feels is important enough to be included in a page summary or table of contents, for example, an area of the page containing live sporting event statistics.
<div>, <frame>, <section>
A row of cells in a grid.
A group containing one or more row elements in a grid.
<thead>, <tfoot>, <tbody>
A cell containing header information for a row in a grid.
A divider that separates and distinguishes sections of content or groups of menuitems.
A collection of commonly used function buttons represented in compact visual form.
The following roles are regions of the page intended as navigational landmarks.
A region declared as a web application, as opposed to a web document.
A region that contains mostly site-oriented content, rather than page-specific content.
<header>, <div class="header">
A supporting section of the document, designed to be complementary to the main content at a similar level in the DOM hierarchy, but remains meaningful when separated from the main content.
A large perceivable region that contains information about the parent document.
A landmark region that contains a collection of items and objects that, as a whole, combine to create a form. See related search
The main content of a document.
<main>, <div class="content">
A collection of navigational elements (usually links) for navigating the document or related documents.
A landmark region that contains a collection of items and objects that, as a whole, combine to create a search facility. See related form.
State and properties
Potential Value Types
|true/false||Value representing either true or false, with a default "false" value.|
|tristate||Value representing true or false, with an intermediate "mixed" value. Default value is "false" unless otherwise specified|
|true/false/undefined||Value representing true or false, with a default "undefined" value indicating the state or property is not relevant.|
|ID reference||Reference to the ID of another element in the same document|
|ID reference list||A list of one or more ID references.|
|integer||A numerical value without a fractional component.|
|number||Any real numerical value.|
|string||Unconstrained value type.|
|token||One of a limited set of allowed values.|
Indicates whether user input completion suggestions are provided.
<element aria-autocomplete="inline|list|both|none" ... />
|inline||The system provides text after the caret as a suggestion for how to complete the field.|
|list||A list of choices appears from which the user can choose, but the edit box retains focus.|
|both||A list of choices appears and the currently selected suggestion also appears inline.|
|none||No input completion suggestions are provided.|
aria-checked - (state)
Indicates the current "checked" state of checkboxes, radio buttons, and other widgets. See related aria-pressed and aria-selected.
<element aria-checked="true|false|mixed" ... >
|true||The element is selected.|
|false||The element is not selected.|
|mixed||The element indicates both selected and unselected states.|
aria-current - (state)
Indicates the element that represents the current item within a container or set of related elements. The aria-current attribute is used when an element within a set of related elements is visually styled to indicate it is the current item in the set.
<element aria-current="page|step|location|date|time|true|false" ... >
|page||Represents the current page within a set of pages.|
|step||Represents the current step within a process.|
|location||Represents the current location within an environment or context.|
|date||Represents the current date within a collection of dates.|
|time||Represents the current time within a set of times.|
|true||Represents the current item within a set.|
|false||(default) Does not represent the current item within a set.|
aria-disabled - (state)
Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. See related aria-hidden and aria-readonly.
<element aria-disabled="true|false" ... >
aria-expanded - (state)
Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
<element aria-expanded="true|false|undefined" ... >
Indicates that the element has a popup context menu or sub-level menu.
<element aria-haspopup="true|false" ... >
aria-hidden - (state)
Indicates that the element and all of its descendants are not visible or perceivable to any user as implemented by the author. See related aria-disabled.
<element aria-hidden="true|false" ... >
aria-invalid - (state)
Indicates the entered value does not conform to the format expected by the application.
<element aria-invalid="true|false|grammar|spelling" ... >
|true||The element is selected.|
|false||The element is not selected.|
|grammar||A grammatical error has been detected.|
|spelling||A spelling error has been detected.|
Defines a string value that labels the current element. See related aria-labelledby.
<element aria-label="string" ... >
Defines the hierarchical level of an element within a structure.
<element aria-level="integer" ... >
Indicates whether a text box accepts multiple lines of input or only a single line.
<element aria-multiline="true|false" ... >
Indicates that the user may select more than one item from the current selectable descendants.
<element aria-multiselectable="true|false" ... >
Indicates whether the element and orientation is horizontal or vertical.
<element aria-orientation="true|false" ... >
|vertical||The element is oriented vertically.|
|horizontal(default)||The element is not selected.|
|grammar||The element is oriented horizontally.|
aria-pressed - (state)
Indicates the current "pressed" state of toggle buttons. See related aria-checked and aria-selected.
<element aria-pressed="true|false|mixed" ... >
Indicates that the element is not editable, but is otherwise operable. See related aria-disabled.
<element aria-readonly="true|false" ... >
Indicates that user input is required on the element before a form may be submitted.
<element aria-required="true|false" ... >
aria-selected - (state)
Indicates the current "selected" state of various widgets. See related aria-checked and aria-pressed.
<element aria-selected="true|false|undefined" ... >
Indicates if items in a table or grid are sorted in ascending or descending order.
<element aria-sort="ascending|descending|none|other" ... />
|ascending||Items are sorted in ascending order by this column.|
|descending||Items are sorted in descending order by this column.|
|none||There is no defined sort applied to the column.|
|other||A sort algorithm other than ascending or descending has been applied.|
Defines the maximum allowed value for a range widget.
<element aria-valuemax="number" ... />
Defines the minimum allowed value for a range widget.
<element aria-valuemin="number" ... />
Defines the current value for a range widget. See related aria-valuetext.
<element aria-valuenow="number" ... />
Defines the human readable text alternative of aria-valuenow for a range widget.
<element aria-valuetext="integer" ... />
Live region attributes
Indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the aria-relevant attribute. See related aria-relevant.
<element aria-atomic="true|false" ... />
aria-busy - (state)
Indicates whether an element, and its subtree, are currently being updated.
<element aria-busy="true|false" ... />
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.
<element aria-live="off|polite|assertive" ... />
|off||Default. Updates should not be announced.|
|polite||Updates should only be announced if the user is idle.|
|assertive||Updates should be announced to the user as soon as possible.|
Indicates what user agent change notifications (additions, removals, etc.) assistive technologies will receive within a live region. See related aria-atomic.
<element aria-relevant="additions|removals|text|all|additions text:" ... />
|additions||Element nodes are added to the DOM within the live region.|
|removals||Text or element nodes within the live region are removed from the DOM.|
|text||Text is added to any DOM descendant nodes of the live region.|
|all||Equivalent to the combination of all values, "additions removals text".|
|additions text(default)||Equivalent to the combination of values, "additions text".|
Indicates what functions can be performed when the dragged object is released on the drop target. This allows assistive technologies to convey the possible drag options available to users, including whether a pop-up menu of choices is provided by the application. Typically, drop effect functions can only be provided once an object has been grabbed for a drag operation as the drop effect functions available are dependent on the object being dragged.
<element aria-grabbed="copy|move|link|execute|popup|none" ... />
|copy||A duplicate of the source object will be dropped into the target.|
|move||The source object will be removed from its current location and dropped into the target.|
|link||A reference or shortcut to the dragged object will be created in the target object.|
|execute||A function supported by the drop target is executed, using the drag source as an input.|
|popup||There is a popup menu or dialog that allows the user to choose one of the drag operations (copy, move, link, execute) and any other drag functionality, such as cancel.|
|none||No operation can be performed; effectively cancels the drag operation if an attempt is made to drop on this object. Ignored if combined with any other token value. e.g. 'none copy' is equivalent to a 'copy' value.|
Indicates an element's "grabbed" state in a drag-and-drop operation.
<element aria-grabbed="true|false|undefined" ... />
Identifies the currently active descendant of a composite widget. Used to deal with multiple focusable children, ie. in a tree menu.
<element aria-activedescendant="#id-reference" ... />
Identifies the element (or elements) whose contents or presence are controlled by the current element. See related aria-owns. Announced for form controls.
<element aria-controls="#id-reference" ... />
Identifies the element (or elements) that describes the object. See related aria-labelledby.
<element aria-describedby="#id-reference" ... />
Identifies the next element (or elements) in an alternate reading order of content which, at the user's discretion, allows assistive technology to override the general default of reading in document source order.
<element aria-flowto="#id-reference" ... />
Identifies the element (or elements) that labels the current element. See related aria-label and aria-describedby.
<element aria-labelledby="#id-reference" ... />
Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between DOM elements where the DOM hierarchy cannot be used to represent the relationship. See related aria-controls.
<element aria-owns="#id-reference" ... />
Defines an element's number or position in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM. See related aria-setsize.
<element aria-posinset="integer" ... />
Defines the number of items in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM. See related aria-posinset.
<element aria-setsize="integer" ... />
MIT © Filipe Linhares