Accessible Rich Internet Applications (WAI-ARIA) 1.0

Skip to Content (Press Enter)

7. Implementation in Host Languages

This section is normative.

The roles, states, and properties defined in this specification do not form a complete web language or format. They are intended to be used in the context of a host language. This section discusses how host languages are to implement WAI-ARIA, to ensure that the markup specified here will integrate smoothly and effectively with the host language markup.

Although markup languages look alike superficially, they do not share language definition infrastructure. To accommodate differences in language-building approaches, the requirements are both general and modularization-specific. While allowing for differences in how the specifications are written, we believe we have maintained consistency in how the WAI-ARIA information looks to authors and how it is manipulated in the DOM by scripts.

WAI-ARIA roles, states, and properties are implemented as attributes of elements. Roles are applied by placing their names among the tokens appearing in the value of a host-language-provided role attribute. States and properties each get their own attribute, with values as defined for each particular state or property in this specification. The name of the attribute is the aria-prefixed name of the state or property.

7.1. Role Attribute

An implementing host language will provide an attribute with the following characteristics:

7.2. State and Property Attributes

An implementing host language MUST allow attributes with the following characteristics:

Following the Namespaces Recommendation [XML-NAMES], the namespace name for these attributes has no value. The names of these attributes do not have a prefix offset by a colon; in the terms of namespaces they are unprefixed attribute names. The ECMAScript binding of the DOM interface getAttributeNS for example, treats an empty string ("") as representing this condition, so that both getAttribute("aria-busy") and getAttributeNS("", "aria-busy") access the same aria-busy attribute in the DOM.

7.3. Focus Navigation

An implementing host language MUST provide support for the author to make all interactive elements focusable, that is, any renderable or event-receiving elements. An implementing host language MUST provide a facility to allow web authors to define whether these focusable, interactive elements appear in the default tab navigation order. The tabindex attribute in HTML 5 is an example of one implementation.

7.4. Implicit WAI-ARIA Semantics

WAI-ARIA is designed to provide semantic information about objects when host languages lack native semantics for the object. WAI-ARIA is designed, however, to provide additional semantics for many host languages. Furthermore, host languages over time can evolve and provide new native features that correspond to ARIA features. Therefore, there are many situations in which WAI-ARIA semantics are redundant with host language semantics.

These host language features can be viewed as having "implict WAI-ARIA semantics". User agent processing of features with implict WAI-ARIA semantics would be similar to the processing for the WAI-ARIA feature. The processing might not be identical because of lexical differences between the host language feature and the WAI-ARIA feature, but generally the user agent would expose the same information to the accessibility API. Features with implicit WAI-ARIA semantics satisfy WAI-ARIA structural requirements such as required owned elements, required states and properties, etc. and do not require explicit WAI-ARIA semantics to be provided.

For example, if an element with the functionality already exists, such as a checkbox or radio button, use the native semantics of the host language. WAI-ARIA markup is only intended to be used to enhance the native semantics (e.g., indicating that the element is required with aria-required), or to change the semantics to a different purpose form the standard functionality of the element.

Implicit WAI-ARIA semantics affects the conflict resolution procedures in the following section, Conflicts with Host Language Semantics. Therefore, implicit WAI-ARIA semantics need to be defined in a normative specification, such as the host language specification or the WAI-ARIA User Agent Implementation Guide [ARIA-IMPLEMENTATION].

7.5. Conflicts with Host Language Semantics

WAI-ARIA is intended to add semantic information to objects when native host language elements are not available with these semantics. It is generally used on elements that have no native semantics of their own with respect to user interface objects. At times, however, it is used on elements that have similar but not identical semantics to the intended object (for instance, nested list elements might be used to represent a tree structure). This is usually done as part of a fallback strategy, or because native presentation of the repurposed element reduces the amount of style and script the author needs to use. In these cases, the user agent MUST use the WAI-ARIA semantics to define how it exposes the element to accessibility APIs, not the native semantics.

Notwithstanding these normal situations in which WAI-ARIA is expected to override native semantics, there are elements that are inappropriate to override with WAI-ARIA. This may be because native semantics already exist so WAI-ARIA is not needed, or because semantics from WAI-ARIA directly conflict with host language semantics. When features in the host language are available for a given type of object, authors SHOULD use those features rather than repurpose other elements with WAI-ARIA. Conformance checkers SHOULD issue a notification when WAI-ARIA is used to provide semantics if features with the same implicit WAI-ARIA semantic is available in the host language.

When WAI-ARIA states and properties correspond to host language features that have the same implicit WAI-ARIA semantic, it can be particularly problematic to use the WAI-ARIA feature. If the WAI-ARIA feature and the host language feature are both provided but their values are not kept in sync, it is uncertain which one is correct. Therefore, user agents MUST ignore WAI-ARIA states and properties when a host language feature with the same implicit WAI-ARIA semantic is provided on the same object. Conformance checkers SHOULD signal an error when WAI-ARIA states and properties are used on the same object as a host language feature with the same implicit WAI-ARIA semantic.

Although host languages can also have features that have implicit WAI-ARIA semantics corresponding to roles, the above rule does not apply to roles. When a WAI-ARIA role is provided, user agents MUST use the semantic of the WAI-ARIA role for processing, not the native semantic. This is because values for roles do not conflict in the same way as values for states and properties, and because authors are expected to have good reason to provide a WAI-ARIA role even on elements that would not normally be repurposed.

Host languages MAY document features that should not be overridden with WAI-ARIA (these are called "strong native semantics"). These can be features that have implicit WAI-ARIA semantics, as well as features where the processing would be uncertain if the semantics were changed with WAI-ARIA. Conformance checkers SHOULD signal an error or warning when a WAI-ARIA role is used on features with strong native semantics, even though user agents process the feature as described above.

7.6. State and Property Attribute Processing

State and property attributes are included in host languages, and therefore syntax for representation of their value types is governed by the host language. For each of the value types defined in Value, an appropriate value type from the host language is used. Recommended correspondences between WAI-ARIA value types and various host language value types are listed in Mapping WAI-ARIA Value types to languages. This is a non-normative mapping in order to accommodate new host languages supporting WAI-ARIA.

The list value types—ID reference list and token list—allow more than one value of the given type to be provided. The values are separated by delimiter characters recognized by the host language for list attributes, such as space characters, commas, etc. Some languages may require a specific, single delimiter, while others may allow various delimiters.

Global states and properties are supported on any element in the host language. However, authors MUST use a WAI-ARIA role on an element in order to use non-global states and properties on that element. When a role attribute is added to an element, the semantics and behavior of the element, including support for WAI-ARIA states and properties, are augmented or overridden by the role behavior. User agents MUST ignore non-global states and properties used on an element without a WAI-ARIA role.

When WAI-ARIA roles are used, supported states and properties that are not present in the DOM are treated according to their default value, unless they are required. For token states and properties, an attribute value that is a zero-length string ("") also corresponds to the default value. Therefore, user agents SHOULD treat token state and property attributes with a value of "" the same as they treat an absent attribute. Normally this corresponds to the default value (usually "undefined"), but if it is a required attribute, they signal an error (because a null value is the same as failing to provide the required attribute).