6. Supported States and Properties

This section is normative.

6.1. Clarification of States versus Properties

The terms "states" and "properties" refer to similar features. Both provide specific information about an object, and both form part of the definition of the nature of roles. In this document, states and properties are both treated as aria-prefixed markup attributes. However, they are maintained conceptually distinct to clarify subtle differences in their meaning. One major difference is that the values of properties (such as aria-labelledby) are often less likely to change throughout the application life-cycle than the values of states (such as aria-checked) which may change frequently due to user interaction. Note that the frequency of change difference is not a rule; a few properties, such as aria-activedescendant, aria-valuenow, and aria-valuetext are expected to change often. Because the distinction between states and properties is of little consequence to most web content authors, this specification refers to both "states" and "properties" simply as "attributes" whenever possible. See the definitions of state and property for more information.

6.2. Characteristics of States and Properties

States and properties have the characteristics described in the following sections.

6.2.1. Related Concepts

Advisory information about features from this or other languages that correspond to this state or property. While the correspondence may not be exact, it is useful to help understand the intent of the state or property.

6.2.2. Used in Roles

Advisory information about roles that use this state or property. This information is provided to help understand the appropriate usage of the state or property. Use of a given state or property is not defined when used on roles other than those listed.

6.2.3. Inherits into Roles

Advisory information about roles that inherit the state or property from an ancestor role.

6.2.4. Value

Value type of the state or property. The value may be one of the following 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.
token list
A list of one or more tokens.
URI
A Uniform Resource Identifier as defined by RFC 3986 [RFC3986]. It may reference a separate document, or a content fragment identifier in a separate document, or a content fragment identifier within the same document.

The "undefined" value, when allowed on a state or property, is an explicit indication that the state or property is not set. The value is used on states and properties that support tokens, and the "undefined" value is a string that is one of the allowed tokens. It is also used on some states and properties that accept true/false values, when "undefined" has a different meaning than "false".

These are generic types for states and properties, but do not define specific representation. See State and Property Attribute Processing for details on how these values are expressed and handled in host languages.

6.3. Values for States and Properties

Many states and properties accept a specific set of tokens as values. The allowed values and explanation of their meaning is shown after the table of characteristics. The default value, if defined, is shown in strong type, followed by the parenthetical term 'default'. When a value is indicated as the default, the user agent MUST follow the behavior prescribed by this value when the state or property is empty or undefined. Some roles also define what behavior to use when certain states or properties, that do not have default values, are not provided.

6.4. Global States and Properties

Some states and properties are applicable to all host language elements regardless of whether a role is applied. The following global states and properties are supported by all roles and by all base markup elements.

Global states and properties are applied to the role roletype, which is the base role, and therefore inherit into all roles. To facilitate reading, they are not explicitly identified as either supported or inherited states and properties in the specification. Instead, the inheritance is indicated by a link to this section.

6.5. Taxonomy of WAI-ARIA States and Properties

States and properties are categorized as follows:

  1. Widget Attributes
  2. Live Region Attributes
  3. Drag-and-Drop Attributes
  4. Relationship Attributes

6.5.1. Widget Attributes

This section contains attributes specific to common user interface elements found on GUI systems or in rich internet applications which receive user input and process user actions. These attributes are used to support the widget roles.

Widget attributes might be mapped by a user agent to platform accessibility API states, for access by assistive technologies, or they might be accessed directly from the DOM. User agents MUST provide a way for assistive technologies to be notified when states change, either through DOM attribute change events or platform accessibility API events.

6.5.2. Live Region Attributes

This section contains attributes specific to live regions in rich internet applications. These attributes may be applied to any element. The purpose of these attributes is to indicate that content changes may occur without the element having focus, and to provide assistive technologies with information on how to process those content updates. Some roles specify a default value for thearia-live attribute specific to that role. An example of a live region is a ticker section that lists updating stock quotes.

6.5.3. Drag-and-Drop Attributes

This section lists attributes which indicate information about drag-and-drop interface elements, such as draggable elements and their drop targets. Drop target information will be rendered visually by the author and provided to assistive technologies through an alternate modality.

For more information about using drag-and-drop, see Drag-and-Drop Support in the WAI-ARIA Authoring Practices ([ARIA-PRACTICES]).

6.5.4. Relationship Attributes

This section lists attributes that indicate relationships or associations between elements which cannot be readily determined from the document structure.

6.6. Definitions of States and Properties (all aria-* attributes)

Below is an alphabetical list of WAI-ARIA states and properties to be used by rich internet application authors. A detailed definition of each WAI-ARIA state and property follows this compact list.

aria-activedescendant
Identifies the currently active descendant of a composite widget.
aria-atomic
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.
aria-autocomplete
Indicates whether user input completion suggestions are provided.
aria-busy (state)
Indicates whether an element, and its subtree, are currently being updated.
aria-checked (state)
Indicates the current "checked" state of checkboxes, radio buttons, and other widgets. See related aria-pressed and aria-selected.
aria-controls
Identifies the element (or elements) whose contents or presence are controlled by the current element. See related aria-owns.
aria-describedat
Specifies a URI referencing content that describes the object. See related aria-describedby.
aria-describedby
Identifies the element (or elements) that describes the object. See related aria-describedat and aria-labelledby.
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.
aria-dropeffect
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.
aria-expanded (state)
Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
aria-flowto
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.
aria-grabbed (state)
Indicates an element's "grabbed" state in a drag-and-drop operation.
aria-haspopup
Indicates that the element has a popup context menu or sub-level menu.
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.
aria-invalid (state)
Indicates the entered value does not conform to the format expected by the application.
aria-label
Defines a string value that labels the current element. See related aria-labelledby.
aria-labelledby
Identifies the element (or elements) that labels the current element. See related aria-label and aria-describedby.
aria-level
Defines the hierarchical level of an element within a structure.
aria-live
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.
aria-multiline
Indicates whether a text box accepts multiple lines of input or only a single line.
aria-multiselectable
Indicates that the user may select more than one item from the current selectable descendants.
aria-orientation
Indicates whether the element and orientation is horizontal or vertical.
aria-owns
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.
aria-posinset
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.
aria-pressed (state)
Indicates the current "pressed" state of toggle buttons. See related aria-checked and aria-selected.
aria-readonly
Indicates that the element is not editable, but is otherwise operable. See related aria-disabled.
aria-relevant
Indicates what user agent change notifications (additions, removals, etc.) assistive technologies will receive within a live region. See related aria-atomic.
aria-required
Indicates that user input is required on the element before a form may be submitted.
aria-selected (state)
Indicates the current "selected" state of various widgets. See related aria-checked and aria-pressed.
aria-setsize
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.
aria-sort
Indicates if items in a table or grid are sorted in ascending or descending order.
aria-valuemax
Defines the maximum allowed value for a range widget.
aria-valuemin
Defines the minimum allowed value for a range widget.
aria-valuenow
Defines the current value for a range widget. See related aria-valuetext.
aria-valuetext
Defines the human readable text alternative of aria-valuenow for a range widget.

aria-activedescendant (property)

Identifies the currently active descendant of a composite widget.

This is used when a composite widget is responsible for managing its current active child to reduce the overhead of having all children be focusable. Examples include: multi-level lists, trees, and grids. In some implementations the user agent may use aria-activedescendant to tell assistive technologies that the active descendant has focus. Authors MAY use the aria-activedescendant attribute on the focused descendant of a composite widget; for example, on a textbox descendant of a combo box.

Authors SHOULD ensure that the element targeted by the aria-activedescendant attribute is either a descendant of the container in the DOM, or is a logical descendant as indicated by thearia-owns attribute. The user agent is not expected to validate that the active descendant is a descendant of the container. Authors SHOULD ensure that the currently active descendant is visible and in view (or scrolls into view) when focused.

Characteristics of aria-activedescendant
CharacteristicValue
Related Concepts:
Used in Roles:
Inherits into Roles:
Value:ID reference

aria-atomic (property)

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.

Both accessibility APIs and the Document Object Model [DOM] provide events to allow the assistive technologies to determine changed areas of the document.

When the content of a live region changes, user agents SHOULD examine the changed element and traverse the ancestors to find the first element with aria-atomic set, and apply the appropriate behavior for the cases below.

  1. If none of the ancestors have explicitly set aria-atomic, the default is that aria-atomic is false, and assistive technologies will only present the changed node to the user.
  2. If aria-atomic is explicitly set to false, assistive technologies will stop searching up the ancestor chain and present only the changed node to the user.
  3. If aria-atomic is explicitly set to true, assistive technologies will present the entire contents of the element.

When aria-atomic is true, assistive technologies MAY choose to combine several changes and present the entire changed region at once.

Characteristics of aria-atomic
CharacteristicValue
Used in Roles:All elements of the base markup
Value:true/false
Values of aria-atomic
ValueDescription
false (default)A change within the region may be processed by the assistive technologies on its own.
trueAssistive technologies will present the entire region as a whole.

aria-autocomplete (property)

Indicates whether user input completion suggestions are provided.

For a textbox with the aria-autocomplete attribute set to either inline or both, authors SHOULD ensure that any auto-completed text is selected, so the user can type over it.

Characteristics of aria-autocomplete
CharacteristicValue
Related Concepts:
Used in Roles:
Value:token
Values of aria-autocomplete
ValueDescription
bothA list of choices appears and the currently selected suggestion also appears inline.
inlineThe system provides text after the caret as a suggestion for how to complete the field.
listA list of choices appears from which the user can choose.
none (default)No input completion suggestions are provided.

aria-busy (state)

Indicates whether an element, and its subtree, are currently being updated.

The default is that aria-busy is false. If authors know that multiple parts of the same element need to be loaded or modified, they can set aria-busy to true when the first part is loaded, and then set aria-busy to false when the last part is loaded. When a widget is missing required owned elements due to script execution or loading, authors MUST mark a containing element with aria-busy equal to true. For example, until a page is fully initialized and complete, an author could mark the document element as busy. If there is an error updating the element, author MAY set the aria-invalid attribute to true.

Characteristics of aria-busy
CharacteristicValue
Used in Roles:All elements of the base markup
Value:true/false
Values of aria-busy
ValueDescription
false (default):There are no more expected updates for the element.
trueThe element is still being updated.

aria-checked (state)

Indicates the current "checked" state of checkboxes, radio buttons, and other widgets. See related aria-pressed and aria-selected.

The aria-checked attribute indicates whether the element is checked (true), unchecked (false), or represents a group of other elements that have a mixture of checked and unchecked values (mixed). Most inputs only support values of true and false, but the mixed value is supported by certain tri-state inputs such as a checkbox or menuitemcheckbox.

The mixed value is not supported on radio or menuitemradio or any element that inherits from these in the taxonomy, and user agents MUST treat a mixed value as equivalent to false for those roles.

Examples using the mixed value of tri-state inputs are covered in WAI-ARIA Authoring Practices [ARIA-PRACTICES]

Characteristics of aria-checked
CharacteristicValue
Used in Roles:option
Inherits into Roles:
Value:tristate
Values of aria-checked
ValueDescription
falseThe element supports being checked but is not currently checked.
mixedIndicates a mixed mode value for a tri-state checkbox or menuitemcheckbox.
trueThe element is checked.
undefined (default)The element does not support being checked.

aria-controls (property)

Identifies the element (or elements) whose contents or presence are controlled by the current element. See related aria-owns.

For example:

  • A table of contents tree view may control the content of a neighboring document pane.
  • A group of checkboxes may control what commodity prices are tracked live in a table or graph.
  • A tab controls the display of its associated tab panel.
Characteristics of aria-controls
CharacteristicValue
Used in Roles:All elements of the base markup
Value:ID reference list

aria-describedat (property)

Specifies a URI referencing content that describes the object. See related aria-describedby.

Authors MUST ensure the URI value of aria-describedat be a valid reference to a separate document, or a content fragment identifier in a separate document, or a content fragment identifier within the same document.

Authors SHOULD should use native markup features and self-describing content where possible (e.g., accessible SVG charts, audio-described video, EPUB footnotes), and only link to external content for descriptions when no other mechanism is available in the host language.

User agents SHOULD provide a device-independent mechanism to allow a user to navigate the user agent to content referenced by the aria-describedat attribute. User agents SHOULD also provide a device-independent mechanism to return the user's focus from the descriptive content view to the original content view. For example, a user agent MAY provide access to the document or document fragment referenced by the the aria-describedat attribute in a contextual menu associated with the object.

In order to provide input- and device-independent access to the associated descriptive content, authors SHOULD use the tabindex attribute to ensure the object is included in the default tab order.

Characteristics of aria-describedat
CharacteristicValue
Related Concepts:
Used in Roles:All elements of the base markup
Value:URI
Example: Using aria-describedat to provide a detailed description for raster images displayed in SVG

This example is informative.

The following example demonstrates three potential ways to use aria-describedat to provide a detailed description of raster images displayed as part of a larger SVG [SVG] document. SVG was used primarily because there is no equivalent mechanism in the host language. The <desc> is arguably similar, but does not allow for structured sub-level content.

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">

  <!-- aria-describedat linking to a separate document -->
  <image x="10" y="10" width="130" height="100"
    aria-label="A painting inspired by Alfred Tennyson's poem The Lady of Shalott"
    aria-describedat="http://example.com/shalott-description"
    xlink:href="http://upload.wikimedia.org/wikipedia/commons/8/83/JWW_TheLadyOfShallot_1888.jpg" />

  <!-- aria-describedat linking to a content fragment identifier in a separate document -->
  <image x="10" y="120" width="130" height="100"
    aria-label="A painting inspired by Alfred Tennyson's poem The Lady of Shalott"
    aria-describedat="http://example.com/descriptions#shalott"
    xlink:href="http://upload.wikimedia.org/wikipedia/commons/8/83/JWW_TheLadyOfShallot_1888.jpg" />

  <!-- aria-describedat linking to a content fragment identifier within the same document (similar to aria-describedby) -->
  <image x="10" y="230" width="130" height="100"
    aria-label="A painting inspired by Alfred Tennyson's poem The Lady of Shalott"
    aria-describedat="#shalott-description"
    xlink:href="http://upload.wikimedia.org/wikipedia/commons/8/83/JWW_TheLadyOfShallot_1888.jpg" />
  <g id="shalott-description">
    <text>
      <tspan role="heading" aria-level="1" x="10" y="360">The Lady of Shallot, oil on canvas by John William Waterhouse, 1888</tspan>
      <tspan x="10" y="380">A small boat on a stream, containing a woman with auburn hair who is surrounded by an ornate tapestry.</tspan>
      <tspan x="10" y="400">The prow of the boat is inscribed "The Lady of Shalott" and is adorned with candles, a crucifix, and a lantern.</tspan>
      <tspan x="10" y="420">Her expression is one of ...</tspan>
    </text>
  </g>

</svg>

aria-describedby (property)

Identifies the element (or elements) that describes the object. See related aria-describedat and aria-labelledby.

The aria-labelledby attribute is similar to aria-describedby in that both reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.

The element or elements referenced by the aria-describedby comprise the entire description. Include ID references to multiple elements if necessary, or enclose a set of elements (e.g., paragraphs) with the element referenced by the ID.

Characteristics of aria-describedby
CharacteristicValue
Related Concepts:
Used in Roles:All elements of the base markup
Value:ID reference list

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.

For example, irrelevant options in a radio group may be disabled. Disabled elements might not receive focus from the tab order. For some disabled elements, applications might choose not to support navigation to descendants. In addition to setting the aria-disabled attribute, authors SHOULD change the appearance (grayed out, etc.) to indicate that the item has been disabled.

The state of being disabled applies to the current element and all focusable descendant elements of the element on which thearia-disabled attribute is applied.

Characteristics of aria-disabled
CharacteristicValue
Used in Roles:All elements of the base markup
Value:true/false
Values of aria-disabled
ValueDescription
false (default)The element is enabled.
trueThe element and all focusable descendants are disabled and its value cannot be changed by the user.

aria-dropeffect (property)

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.

More than one drop effect may be supported for a given element. Therefore, the value of this attribute is a space-delimited set of tokens indicating the possible effects, or none if there is no supported operation. In addition to setting the aria-dropeffect attribute, authors SHOULD show a visual indication of potential drop targets.

Characteristics of aria-dropeffect
CharacteristicValue
Used in Roles:All elements of the base markup
Value:token list
Values of aria-dropeffect
ValueDescription
copyA duplicate of the source object will be dropped into the target.
executeA function supported by the drop target is executed, using the drag source as an input.
linkA reference or shortcut to the dragged object will be created in the target object.
moveThe source object will be removed from its current location and dropped into the target.
none (default)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.
popupThere 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.

aria-expanded (state)

Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.

For example, this indicates whether a portion of a tree is expanded or collapsed. In other instances, this may be applied to page sections to mark expandable and collapsible regions that are flexible for managing content density. Simplifying the user interface by collapsing sections may improve usability for all, including those with cognitive or developmental disabilities.

If the element with the aria-expanded attribute controls the expansion of another grouping container that is not 'owned by' the element, the author SHOULD reference the container by using the aria-controls attribute.

Characteristics of aria-expanded
CharacteristicValue
Related Concepts:
Used in Roles:
Inherits into Roles:
Value:true/false/undefined
Values of aria-expanded
ValueDescription
falseThe element, or another grouping element it controls, is collapsed.
trueThe element, or another grouping element it controls, is expanded.
undefined (default)The element, or another grouping element it controls, is neither expandable nor collapsible; all its child elements are shown or there are no child elements.

aria-flowto (property)

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.

When aria-flowto has a single IDREF, it allows assistive technologies to, at the user's request, forego normal document reading order and go to the targeted object. However, when aria-flowto is provided with multiple IDREFS, assistive technologies SHOULD present the referenced elements as path choices.

In the case of one or more IDREFS, user agents or assistive technologies SHOULD give the user the option of navigating to any of the targeted elements. The name of the path can be determined by the name of the target element of the aria-flowto attribute. Accessibility APIs can provide named path relationships.

Characteristics of aria-flowto
CharacteristicValue
Used in Roles:All elements of the base markup
Value:ID reference list

aria-grabbed (state)

Indicates an element's "grabbed" state in a drag-and-drop operation.

When it is set to true it has been selected for dragging, false indicates that the element can be grabbed for a drag-and-drop operation, but is not currently grabbed, and undefined (or no value) indicates the element cannot be grabbed (default).

When aria-grabbed is set to true, authors SHOULD update the aria-dropeffect attribute of all potential drop targets. When an element is not grabbed (the value is set to false, undefined, or the attribute is removed), authors SHOULD revert the aria-dropeffect attributes of the associated drop targets to none.

Characteristics of aria-grabbed
CharacteristicValue
Used in Roles:All elements of the base markup
Value:true/false/undefined
Values of aria-grabbed
ValueDescription
falseIndicates that the element supports being dragged.
trueIndicates that the element has been "grabbed" for dragging.
undefined (default)Indicates that the element does not support being dragged.

aria-haspopup (property)

Indicates that the element has a popup context menu or sub-level menu.

This means that activation renders conditional content. Note that ordinary tooltips are not considered popups in this context.

A popup is generally presented visually as a group of items that appears to be on top of the main page content.

Characteristics of aria-haspopup
CharacteristicValue
Related Concepts:
Used in Roles:All elements of the base markup
Value:true/false
Values of aria-haspopup
ValueDescription
false (default)The object has no popup.
trueIndicates the object has a popup, either as a descendant or pointed to by aria-owns.

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.

If an element is only visible after some user action, authors MUST set the aria-hidden attribute to true. When the element is presented, authors MUST set the aria-hidden attribute to false or remove the attribute, indicating that the element is visible. Some assistive technologies access WAI-ARIA information directly through the DOM and not through platform accessibility supported by the browser. Authors MUST set aria-hidden="true" on content that is not displayed, regardless of the mechanism used to hide it. This allows assistive technologies or user agents to properly skip hidden elements in the document.

It is recommended that authors key visibility of elements off this attribute, rather than change visibility and separately have to remember to update this property. CSS 2 provides a way to select on attribute values ([CSS]). The following CSS declaration makes content visible unless the aria-hidden attribute is true; scripts need only update the value of this attribute to change visibility:

[aria-hidden="true"] { visibility: hidden; }

Note: Authors are reminded that visibility:hidden and display:none apply to all CSS media types; therefore, use of either will hide the content from assistive technologies that access the DOM through a rendering engine. However, in order to support assistive technologies that access the DOM directly, or other authoring techniques to visibly hide content (for example, opacity or off-screen positioning), authors need to ensure the aria-hidden attribute is always updated accordingly when an element is shown or hidden, unless the intent of using off-screen positioning is to make the content visible only to screen reader users and not others.

Authors MAY, with caution, use aria-hidden to hide visibly rendered content from assistive technologies only if the act of hiding this content is intended to improve the experience for users of assistive technologies by removing redundant or extraneous content. Authors using aria-hidden to hide visible content from screen readers MUST ensure that identical or equivalent meaning and functionality is exposed to assistive technologies.

Note: Authors are advised to use extreme caution and consider a wide range of disabilities when hiding visibly rendered content from assistive technologies. For example, a sighted, dexterity-impaired individual may use voice-controlled assistive technologies to access a visual interface. If an author hides visible link text "Go to checkout" and exposes similar, yet non-identical link text "Check out now" to the accessibility API, the user may be unable to access the interface they perceive using voice control. Similar problems may also arise for screen reader users. For example, a sighted telephone support technician may attempt to have the blind screen reader user click the "Go to checkout" link, which they may be unable to find using a type-ahead item search ("Go to…").

Characteristics of aria-hidden
CharacteristicValue
Used in Roles:All elements of the base markup
Value:true/false
Values of aria-hidden
ValueDescription
false (default)Indicates that this section of the document is rendered.
trueIndicates that this section of the document and its children are hidden from the rendered view.

Note: Authors are advised to avoid using aria-hidden="false" with styles or attributes that have historically prevented rendering in all modalities, such as display:none or visibility:hidden in CSS, or the hidden attribute in HTML 5. At the time of this writing, aria-hidden="false" is known to work inconsistently when used in conjunction with such features. As future implementations improve, use caution and test thoroughly before relying on this approach.


aria-invalid (state)

Indicates the entered value does not conform to the format expected by the application.

If the value is computed to be invalid or out-of-range, the application author SHOULD set this attribute to true. User agents SHOULD inform the user of the error. Application authors SHOULD provide suggestions for corrections if they are known.

When the user attempts to submit data involving a field for whicharia-required is true, authors MAY use the aria-invalid attribute to signal there is an error. However, if the user has not attempted to submit the form, authors SHOULD NOT set the aria-invalid attribute on required widgets simply because the user has not yet entered data.

For future expansion, the aria-invalid attribute is an enumerated type. Any value not recognized in the list of allowed values MUST be treated by user agents as if the value true had been provided. If the attribute is not present, or its value is false, or its value is an empty string, the default value of false applies.

Characteristics of aria-invalid
CharacteristicValue
Related Concepts:
Used in Roles:All elements of the base markup
Value:token
Values of aria-invalid
ValueDescription
grammarA grammatical error was detected.
false (default)There are no detected errors in the value.
spellingA spelling error was detected.
trueThe value entered by the user has failed validation.

aria-label (property)

Defines a string value that labels the current element. See related aria-labelledby.

The purpose of aria-label is the same as that of aria-labelledby. It provides the user with a recognizable name of the object. The most common accessibility API mapping for a label is the accessible name property.

If the label text is visible on screen, authors SHOULD use aria-labelledby and SHOULD NOT use aria-label. There may be instances where the name of an element cannot be determined programmatically from the content of the element, and there are cases where providing a visible label is not the desired user experience. Most host languages provide an attribute that could be used to name the element (e.g., the title attribute in HTML [HTML]), yet this could present a browser tooltip. In the cases where a visible label or visible tooltip is undesirable, authors MAY set the accessible name of the element using aria-label. As required by the text alternative computation, user agents give precedence to aria-labelledby over aria-label when computing the accessible name property.

Characteristics of aria-label
CharacteristicValue
Related Concepts:
Used in Roles:All elements of the base markup
Value:string

aria-labelledby (property)

Identifies the element (or elements) that labels the current element. See related aria-label and aria-describedby.

The purpose of aria-labelledby is the same as that of aria-label. It provides the user with a recognizable name of the object. The most common accessibility API mapping for a label is the accessible name property.

If the label text is visible on screen, authors SHOULD use aria-labelledby and SHOULD NOT use aria-label. Use aria-label only if the interface is such that it is not possible to have a visible label on the screen. As required by the text alternative computation, user agents give precedence to aria-labelledby over aria-label when computing the accessible name property.

The aria-labelledby attribute is similar to aria-describedby in that both reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.

Note: The expected spelling of this property in U.S. English is "labeledby." However, the accessibility API features to which this property is mapped have established the "labelledby" spelling. This property is spelled that way to match the convention and minimize the difficulty for developers.

Characteristics of aria-labelledby
CharacteristicValue
Related Concepts:
Used in Roles:All elements of the base markup
Value:ID reference list

aria-level (property)

Defines the hierarchical level of an element within a structure.

This can be applied inside trees to tree items, to headings inside a document, to nested grids, nested tablists and to other structural items that may appear inside a container or participate in an ownership hierarchy. The value for aria-level is an integer greater than or equal to 1.

Levels increase with depth. If the DOM ancestry does not accurately represent the level, authors SHOULD explicitly define the aria-level attribute.

This attribute is applied to elements that act as leaf nodes within the orientation of the set, for example, on elements with role treeitem rather than elements with role group. This means that multiple elements in a set may have the same value for this attribute. Although it would be less repetitive to provide a single value on the container, restricting this to leaf nodes ensures that there is a single way for assistive technologies to use the attribute.

If the DOM ancestry accurately represents the level, the user agent can calculate the level of an item from the document structure. This attribute can be used to provide an explicit indication of the level when that is not possible to calculate from the document structure or thearia-owns attribute. User agent support for automatic calculation of level may vary; authors SHOULD test with user agents and assistive technologies to determine whether this attribute is needed. If the author intends for the user agent to calculate the level, the author SHOULD omit this attribute.

Note: In the case of a treegrid, aria-level is supported on elements with the role row, not elements with role gridcell. At first glance, this may seem inconsistent with the application of aria-level on treeitem elements, but it is consistent in that the row acts as the leaf node within the vertical orientation of the grid, whereas the gridcell is a leaf node within the horizontal orientation of each row. Level is not supported on sets of cells within rows, so the aria-level attribute is applied to the element with the role row.

Characteristics of aria-level
CharacteristicValue
Used in Roles:
Inherits into Roles:
Value:integer

aria-live (property)

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.

The values of this attribute are expressed in degrees of importance. When regions are specified as polite, assistive technologies will notify users of updates but generally do not interrupt the current task, and updates take low priority. When regions are specified as assertive, assistive technologies will immediately notify the user, and could potentially clear the speech queue of previous updates. Please refer to Live Region Properties and How to Use Them ([ARIA-PRACTICES], Section 5.2.1).

Politeness levels are essentially an ordering mechanism for updates and serve as a strong suggestion to user agents or assistive technologies. The value may be overridden by user agents, assistive technologies, or the user. For example, if assistive technologies can determine that a change occurred in response to a key press or a mouse click, the assistive technologies may present that change immediately even if the value of the aria-live attribute states otherwise.

Since different users have different needs, it is up to the user to tweak his or her assistive technologies' response to a live region with a certain politeness level from the commonly defined baseline. Assistive technologies may choose to implement increasing and decreasing levels of granularity so that the user can exercise control over queues and interruptions.

When the property is not set on an object that needs to send updates, the politeness level is the value of the nearest ancestor that sets the aria-live attribute.

The aria-live attribute is the primary determination for the order of presentation of changes to live regions. Implementations will also consider the default level of politeness in a role when the aria-live attribute is not set in the ancestor chain (e.g., log changes are polite by default). Items which are assertive will be presented immediately, followed by polite items. User agents or assistive technologies MAY choose to clear queued changes when an assertive change occurs. (e.g., changes in an assertive region may remove all currently queued changes)

When live regions are marked as polite, assistive technologies SHOULD announce updates at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses typing. When live regions are marked as assertive, assistive technologies SHOULD notify the user immediately. Because an interruption may disorient users or cause them to not complete their current task, authors SHOULD NOT use the assertive value unless the interruption is imperative.

Characteristics of aria-live
CharacteristicValue
Used in Roles:All elements of the base markup
Value:token
Values of aria-live
ValueDescription
assertiveIndicates that updates to the region have the highest priority and should be presented the user immediately.
off (default)Indicates that updates to the region should not be presented to the user unless the used is currently focused on that region.
politeIndicates 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.

aria-multiline (property)

Indicates whether a text box accepts multiple lines of input or only a single line.

Note: In most user agent implementations, the default behavior of the ENTER or RETURN key is different between the single-line and multi-line text fields in HTML. When user has focus in a single-line <input type="text"> element, the keystroke usually submits the form. When user has focus in a multi-line <textarea> element, the keystroke inserts a line break. The WAI-ARIA textbox role differentiates these types of boxes with the aria-multiline attribute, so authors are advised to be aware of this distinction when designing the field.

Characteristics of aria-multiline
CharacteristicValue
Used in Roles:textbox
Value:true/false
Values of aria-multiline
ValueDescription
false (default)This is a single-line text box.
trueThis is a multi-line text box.

aria-multiselectable (property)

Indicates that the user may select more than one item from the current selectable descendants.

Authors SHOULD ensure that selected descendants have thearia-selected attribute set to true, and selectable descendant have thearia-selected attribute set to false. Authors SHOULD NOT use thearia-selected attribute on descendants that are not selectable.

Note: Lists and trees are examples of roles that might allow users to select more than one item at a time.

Characteristics of aria-multiselectable
CharacteristicValue
Used in Roles:
Inherits into Roles:
Value:true/false
Values of aria-multiselectable
ValueDescription
false (default)Only one item can be selected.
trueMore than one item in the widget may be selected at a time.

aria-orientation (property)

Indicates whether the element and orientation is horizontal or vertical.

Characteristics of aria-orientation
CharacteristicValue
Used in Roles:
Value:token
Values of aria-orientation
ValueDescription
horizontal (default)The element is oriented horizontally.
verticalThe element is oriented vertically.

aria-owns (property)

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.

The value of the aria-owns attribute is a space-separated list of IDREFS that reference one or more elements in the document by ID. The reason for adding aria-owns is to expose a parent/child contextual relationship to assistive technologies that is otherwise impossible to infer from the DOM.

Authors SHOULD NOT use aria-owns as a replacement for the DOM hierarchy. If the relationship is represented in the DOM, do not use aria-owns. Authors MUST ensure that an element's ID is not specified in more than one other element's aria-owns attribute at any time. In other words, an element can have only one explicit owner.

Characteristics of aria-owns
CharacteristicValue
Used in Roles:All elements of the base markup
Value:ID reference list

aria-posinset (property)

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.

If all items in a set are present in the document structure, it is not necessary to set this attribute, as the user agent can automatically calculate the set size and position for each item. However, if only a portion of the set is present in the document structure at a given moment, this property is needed to provide an explicit indication of an element's position.

The following example shows items 5 through 8 in a set of 16.

<h2 id="label_fruit"> Available Fruit </h2>
<ul role="listbox" aria-labelledby="label_fruit">
  <li role="option" aria-setsize="16" aria-posinset="5"> apples </li>
  <li role="option" aria-setsize="16" aria-posinset="6"> bananas </li>
  <li role="option" aria-setsize="16" aria-posinset="7"> cantaloupes </li>
  <li role="option" aria-setsize="16" aria-posinset="8"> dates </li>
</ul>

Authors MUST set the value for aria-posinset to an integer greater than or equal to 1, and less than or equal to the size of the set. Authors SHOULD use aria-posinset in conjunction with aria-setsize.

Characteristics of aria-posinset
CharacteristicValue
Used in Roles:
Inherits into Roles:
Value:integer

aria-pressed (state)

Indicates the current "pressed" state of toggle buttons. See related aria-checked and aria-selected.

Toggle buttons require a full press-and-release cycle to change their value. Activating it once changes the value to true, and activating it another time changes the value back to false. A value of mixed means that the values of more than one item controlled by the button do not all share the same value. Examples of mixed-state buttons are described in WAI-ARIA Authoring Practices [ARIA-PRACTICES]. If the attribute is not present, the button is not a toggle button.

The aria-pressed attribute is similar but not identical to thearia-checked attribute. Operating systems support pressed on buttons and checked on checkboxes.

Characteristics of aria-pressed
CharacteristicValue
Used in Roles:button
Value:tristate
Values of aria-pressed
ValueDescription
falseThe element supports being pressed but is not currently pressed.
mixedIndicates a mixed mode value for a tri-state toggle button.
trueThe element is pressed.
undefined (default)The element does not support being pressed.

aria-readonly (property)

Indicates that the element is not editable, but is otherwise operable. See related aria-disabled.

This means the user can read but not set the value of the widget. Readonly elements are relevant to the user, and application authors SHOULD NOT restrict navigation to the element or its focusable descendants. Other actions such as copying the value of the element are also supported. This is in contrast to disabled elements, to which applications might not allow user navigation to descendants.

Examples include:

  • A form element which represents a constant.
  • Row or column headers in a spreadsheet grid.
  • The result of a calculation such as a shopping cart total.
Characteristics of aria-readonly
CharacteristicValue
Related Concepts:
Used in Roles:
Inherits into Roles:
Value:true/false
Values of aria-readonly
ValueDescription
false (default)The user can set the value of the element.
trueThe user cannot change the value of the element.

aria-relevant (property)

Indicates what user agent change notifications (additions, removals, etc.) assistive technologies will receive within a live region. See related aria-atomic.

The attribute is represented as a space delimited list of the following values: additions, removals, text; or a single catch-all value all.

This is used to describe semantically meaningful changes, as opposed to merely presentational ones. For example, nodes that are removed from the top of a log are merely removed for purposes of creating room for other entries, and the removal of them does not have meaning. However, in the case of a buddy list, removal of a buddy name indicates that they are no longer online, and this is a meaningful event. In that case aria-relevant will be set to all. When the aria-relevant attribute is not provided, the default value, additions text, indicates that text modifications and node additions are relevant, but that node removals are irrelevant.

Note: aria-relevant values of removals or all are to be used sparingly. Assistive technologies only need to be informed of content removal when its removal represents an important change, such as a buddy leaving a chat room.

Note: Text removals should only be considered relevant if one of the specified values is 'removals' or 'all'. For example, for a text change from 'foo' to 'bar' in a live region with a default aria-relevant value, the text addition ('bar') would be spoken, but the text removal ('foo') would not.

aria-relevant is an optional attribute of live regions. This is a suggestion to assistive technologies, but assistive technologies are not required to present changes of all the relevant types.

Both accessibility APIs and Document Object Model Level 2 Events [DOM] provides events to allow assistive technologies to determine changed areas of the document.

When aria-relevant is not defined, an element's value is inherited from the nearest ancestor with a defined value. Although the value is a token list, inherited values are not additive; the value provided on a descendant element completely overrides any inherited value from an ancestor element.

When text changes are denoted as relevant, user agents MUST monitor any descendant node change that affects the text alternative computation of the live region as if the accessible name were determined from contents (nameFrom: contents). For example, a text change would be triggered if the HTML alt attribute of a contained image changed. However, no change would be triggered if there was a text change to a node outside the live region, even if that node was referenced (via aria-labelledby) by an element contained in the live region.

Characteristics of aria-relevant
CharacteristicValue
Used in Roles:All elements of the base markup
Value:token list
Values of aria-relevant
ValueDescription
additionsElement nodes are added to the DOM within the live region.
additions text (default)Equivalent to the combination of values, "additions text".
allEquivalent to the combination of all values, "additions removals text".
removalsText or element nodes within the live region are removed from the DOM.
textText is added to any DOM descendant nodes of the live region.

aria-required (property)

Indicates that user input is required on the element before a form may be submitted.

For example, if the user needs to fill in an address field, the author will need to set the field's aria-required attribute to true.

Note: The fact that the element is required is often presented visually (such as a sign or symbol after the widget). Using the aria-required attribute allows the author to explicitly convey to assistive technologies that an element is required.

Unless an exactly equivalent native attribute is available, host languages SHOULD allow authors to use the aria-required attribute on host language form elements that require input or selection by the user.

Characteristics of aria-required
CharacteristicValue
Related Concepts:
Used in Roles:
Inherits into Roles:
Value:true/false
Values of aria-required
ValueDescription
false (default)User input is not necessary to submit the form.
trueUsers need to provide input on an element before a form is submitted.

aria-selected (state)

Indicates the current "selected" state of various widgets. See related aria-checked and aria-pressed.

This attribute is used with single-selection and multiple-selection widgets:

  1. Single-selection containers where the currently focused item is not selected. The selection normally follows the focus, and is managed by the user agent.
  2. Multiple-selection containers. Authors SHOULD ensure that any selectable descendant of a container in which thearia-multiselectable attribute is true specifies a value of either true or false for the aria-selected attribute.

Any explicit assignment of aria-selected takes precedence over the implicit selection based on focus. If no DOM element in the widget is explicitly marked as selected, assistive technologies MAY convey implicit selection which follows the keyboard focus of the managed focus widget. If any DOM element in the widget is explicitly marked as selected, the user agent MUST NOT convey implicit selection for the widget.

Characteristics of aria-selected
CharacteristicValue
Used in Roles:
Inherits into Roles:
Value:true/false/undefined
Values of aria-selected
ValueDescription
falseThe selectable element is not selected.
trueThe selectable element is selected.
undefined (default)The element is not selectable.

aria-setsize (property)

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.

This property is marked on the members of a set, not the container element that collects the members of the set. To orient the user by saying an element is "item X out of Y," the assistive technologies would use X equal to the aria-posinset attribute and Y equal to the aria-setsize attribute.

If all items in a set are present in the document structure, it is not necessary to set this property, as the user agent can automatically calculate the set size and position for each item. However, if only a portion of the set is present in the document structure at a given moment (in order to reduce document size), this property is needed to provide an explicit indication of set size.

The following example shows items 5 through 8 in a set of 16.

<h2 id="label_fruit"> Available Fruit </h2>
<ul role="listbox" aria-labelledby="label_fruit">
  <li role="option" aria-setsize="16" aria-posinset="5"> apples </li>
  <li role="option" aria-setsize="16" aria-posinset="6"> bananas </li>
  <li role="option" aria-setsize="16" aria-posinset="7"> cantaloupes </li>
  <li role="option" aria-setsize="16" aria-posinset="8"> dates </li>
</ul>

Authors SHOULD use aria-setsize in conjunction with aria-posinset.

Characteristics of aria-setsize
CharacteristicValue
Used in Roles:
Inherits into Roles:
Value:integer

aria-sort (property)

Indicates if items in a table or grid are sorted in ascending or descending order.

Authors SHOULD only apply this property to table headers or grid headers. If the property is not provided, there is no defined sort order. For each table or grid, authors SHOULD apply aria-sort to only one header at a time.

Characteristics of aria-sort
CharacteristicValue
Used in Roles:
Value:token
Values of aria-sort
ValueDescription
ascendingItems are sorted in ascending order by this column.
descendingItems are sorted in descending order by this column.
none (default)There is no defined sort applied to the column.
otherA sort algorithm other than ascending or descending has been applied.

aria-valuemax (property)

Defines the maximum allowed value for a range widget.

A range widget may start with a given value, which can be increased until a maximum value, defined by this property, is reached.

If thearia-valuenow has a known maximum and minimum, the author SHOULD provide properties for aria-valuemax andaria-valuemin. Authors MUST ensure the value of aria-valuemax is greater than or equal to the value of aria-valuemin.

Characteristics of aria-valuemax
CharacteristicValue
Related Concepts:
Used in Roles:
Inherits into Roles:
Value:number

aria-valuemin (property)

Defines the minimum allowed value for a range widget.

A range widget may start with a given value, which can be decreased until a minimum value, defined by this property, is reached.

Declaring the minimum and maximum values allows alternate devices to react to arrow keys, validate the current value, or simply let the user know the size of the range. If thearia-valuenow has a known maximum and minimum, the author SHOULD provide properties foraria-valuemax and aria-valuemin.

Authors MUST ensure the value of aria-valuemin is less than or equal to the value of aria-valuemax.

Characteristics of aria-valuemin
CharacteristicValue
Related Concepts:
Used in Roles:
Inherits into Roles:
Value:number

aria-valuenow (property)

Defines the current value for a range widget. See related aria-valuetext.

This property is used, for example, on a range widget such as a slider or progress bar.

If the current value is not known (for example, an indeterminate progress bar), the author SHOULD NOT set the aria-valuenow attribute. If the aria-valuenow attribute is absent, no information is implied about the current value. If the aria-valuenow has a known maximum and minimum, the author SHOULD provide properties foraria-valuemax and aria-valuemin.

The value of aria-valuenow is a decimal number. If the range is a set of numeric values, then aria-valuenow is one of those values. For example, if the range is [0, 1], a valid aria-valuenow is 0.5. A value outside the range, such as -2.5 or 1.1, is invalid.

For progressbar elements and scrollbar elements, assistive technologies SHOULD render the value to users as a percent, calculated as a position on the range from aria-valuemin to aria-valuemax if both are defined, otherwise the actual value with a percent indicator. For elements with role slider and spinbutton, assistive technologies SHOULD render the actual value to users.

When the rendered value cannot be accurately represented as a number, authors SHOULD use the aria-valuetext attribute in conjunction with aria-valuenow to provide a user-friendly representation of the range's current value. For example, a slider may have rendered values of small, medium, and large. In this case, the values of aria-valuenow could range from 1 through 3, which indicate the position of each value in the value space, but the aria-valuetext would be one of the strings: small, medium, or large.

Note: If aria-valuetext is specified, assistive technologies render that instead of the value of aria-valuenow.

Characteristics of aria-valuenow
CharacteristicValue
Related Concepts:
Used in Roles:
Inherits into Roles:
Value:number

aria-valuetext (property)

Defines the human readable text alternative of aria-valuenow for a range widget.

This property is used, for example, on a range widget such as a slider or progress bar.

If the aria-valuetext attribute is set, authors SHOULD also set the aria-valuenow attribute, unless that value is unknown (for example, on an indeterminate progressbar).

Authors SHOULD only set the aria-valuetext attribute when the rendered value cannot be meaningfully represented as a number. For example, a slider may have rendered values of small, medium, and large. In this case, the values ofaria-valuenow could range from 1 through 3, which indicate the position of each value in the value space, but the aria-valuetext would be one of the strings: small, medium, or large. If the aria-valuetext attribute is absent, the assistive technologies will rely solely on the aria-valuenow attribute for the current value.

If aria-valuetext is specified, assistive technologies SHOULD render that value instead of the value of aria-valuenow.

Characteristics of aria-valuetext
CharacteristicValue
Related Concepts:
Used in Roles:
Inherits into Roles:
Value:string