6. Supported States and Properties

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 SHOULD ensure that the element targeted by the activedescendant attribute is either a descendant of the container in the DOM, or is a logical descendant as indicated by the aria-owns attribute. The user agent is not expected to check that the active descendant is an actual descendant of the container. Authors SHOULD ensure that the currently active descendant remains visible and in view. Authors SHOULD capture changes to the activedescendant attribute, which may occur if the assistive technologies or user agents set focus directly.

Indicates whether the assistive technology will present all, or only parts of, the changed region based on the change notifications defined by the aria-relevant attribute. Also see 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 technology will only present the changed node to the user.
2. If aria-atomic is explicitly set to false, assistive technology 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 technology will present the entire contents of the element.

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

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 the auto-completion text is selected and comes previously typed character, so the user can type over it. The aria-haspopup attribute can be used in conjunction with this to indicate that a popup containing choices appears, notwithstanding the fact that it is a simple text box.

For an element which already has a drop-down (i.e., a combobox), it is assumed that the dropdown behavior is still present. This means that if autocomplete is true, aria-haspopup will also be true on a combobox.

Identifies the element (or elements) whose contents or presence are controlled by the current element. Also see 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.

Identifies the element (or elements) that describes the object. Also see aria-labelledby.

This is very similar to labeling an object with aria-labelledby. A label provides the user with the essence of what the object does, whereas a description is intended to provide additional detail that some users might need.

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.

Identifies the next element (or elements) in the recommended reading order of content, overriding the general default to read 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. aria-flowto in subsequent elements would follow a process similar to next focus in XHTML2 ([XHTML]). However, when aria-flowto is provided with multiple IDREFS, assistive technology SHOULD present the referenced elements as path choices.

In the case of one or more IDREFS, user agents or assistive technologies SHOULD give a user the option of navigating to any of the elements targeted. 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.

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. When presenting a menu, authors SHOULD ensure that the menu is completely visible on screen.

Defines a string value that labels the current element when included as an attribute of the current element. Also see 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 may 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.

Identifies the element (or elements) that labels the current element. Also see 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.

The aria-labelledby attribute is very similar to describing an object with aria-describedby, where a description is intended to provide additional information that some users might need.

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.

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

Unless supported on a grouping element (such as in the case of the row), this attribute is applied to leaf nodes (elements that receive focus), not to the parent grouping element, even when all siblings are at the same level. 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 technology 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 the aria-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, rather than on the leaf node gridcell. In all other instances, aria-level is applied on the leaf nodes; for example, on a treeitem in a tree.

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 terms of politeness levels. Regions specified as polite will notify users of updates but generally do not interrupt the current task, and updates take low priority. Use the assertive value when the update needs to be communicated to the user more urgently, for example, warning or error messages in a form that does immediate validation for each form field.

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 technology MAY choose to clear queued changes when an assertive change occurs. (e.g. changes in an assertive region may remove all currently queued changes)

Indicates whether a text box accepts only a single line, or if it can accept multiline input.

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

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

Lists, trees, and grids may allow users to select more than one item at a time.

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

Indicates whether the element and scrolling orientation is horizontal or vertical.

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. Also see 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 IDREF 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.

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. Also see 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 1 through 4 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="1"> apples </li>
  <li role="option" aria-setsize="16" aria-posinset="2"> bananas </li>
  <li role="option" aria-setsize="16" aria-posinset="3"> cantalopes </li>
  <li role="option" aria-setsize="16" aria-posinset="4"> 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.

Indicates that the element is not editable, but is otherwise operable. Also see 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.

Indicates what user agent change notifications (additions, removals, etc.) assistive technology will monitor within a live region. Also see 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 is to assume that text modifications and node additions are relevant, and 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.

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.

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

For example, if a 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.

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. Also see 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 a 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 1 through 4 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="1"> apples </li>
  <li role="option" aria-setsize="16" aria-posinset="2"> bananas </li>
  <li role="option" aria-setsize="16" aria-posinset="3"> cantalopes </li>
  <li role="option" aria-setsize="16" aria-posinset="4"> dates </li>
</ul>

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

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.

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.

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 the aria-valuenow has a known maximum and minimum, the author SHOULD provide properties for aria-valuemax and aria-valuemin. The value of aria-valuemin SHOULD be less than or equal to the value of aria-valuemax. If not, or the aria-valuemax is indeterminate, this is considered to be an error condition that will be handled by assistive technologies resulting in undesirable results.

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 the aria-valuenow has a known maximum and minimum, the author SHOULD provide properties for aria-valuemax and aria-valuemin.

Defines the current value for a range widget. Also see aria-valuetext.

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

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.

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

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 accurately represented as a number. 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. If the aria-valuetext attribute is absent, the assistive technologies will rely solely on the aria-valuenow attribute for the current value.