# Using WAI-ARIA state and property attributes to expose the state of a user interface component

ID: ARIA5

Technology: aria

Type: Technique

## When to Use

Technologies that support Accessible Rich Internet Applications (WAI-ARIA).

## Description

The objective of this technique is to use WAI-ARIA state and property attributes to expose the state, properties and values of a user interface component so that they can be read and set by assistive technology, and so that assistive technology is notified of changes to these values. The WAI-ARIA specification provides a normative description of each attribute, and the role of the user interface elements that they support. When rich internet applications define new user interface widgets, exposing the state and property attributes enables users to understand the widget and how to interact with it.

## Examples

### A toggle button

A widget with role `button` acts as a toggle button when it implements the attribute `aria-pressed`. When `aria-pressed` is true, the button is in a "pressed" state. When `aria-pressed` is false, it is not pressed. If the attribute is not present, the button is a simple command button.

The following snippet from the ARIA Authoring Practices Guide (APG) examples for button shows WAI-ARIA mark-up for a toggle button to mute/unmute audio:

    <a tabindex="0"
      role="button"
      id="toggle"
      aria-pressed="false">
      Mute
      ...
    </a>

The `a` element has a `role="button"` and an `aria-pressed` attribute. The following excerpt from the Javascript for this example updates the value of the `aria-pressed` attribute:

    /**
    * Toggles the toggle button's state between *pressed* and *not pressed*.
    *
    * @param {HTMLElement} button
    */

    function toggleButtonState(button) {
      var isAriaPressed = button.getAttribute('aria-pressed') === 'true';
      button.setAttribute('aria-pressed', isAriaPressed ? 'false' : 'true');
      ...
    }

### A slider

A widget with role `slider` lets a user select a value from within a given range. The slider represents the current value and the range of possible values via the size of the slider and the position of the handle. These properties of the slider are represented by the attributes `aria-valuemin`, `aria-valuemax`, and `aria-valuenow`.

The following snippet from the ARIA Authoring Practices Guide (APG) color viewer slider example shows WAI-ARIA mark-up for one of the sliders:

    <div id="id-red" class="color-slider-label">Red</div>
    <div class="color-slider red"
      role="slider"
      tabindex="0"
      aria-valuemin="0"
      aria-valuenow="128"
      aria-valuemax="255"
      aria-labelledby="id-red">
       ...
    </div>

The following excerpt from the Javascript for this example updates the value of the `aria-valuenow` attribute when the value of the slider handle is changed:

    moveSliderTo(slider, value) {
      ...
      slider.sliderNode.setAttribute('aria-valuenow', value);
      ...
    }

## Tests

### Procedure

The WAI-ARIA specification, Section 5.3, Categorization of Roles defines the required and inherited states and properties for each role.

For a user interface component using the WAI-ARIA role attribute:

1. Check that the required states and properties for the role are present.
2. Check that no WAI-ARIA states or properties that are neither required, supported, nor inherited are present.
3. Check that the state and property values are updated to reflect the current state when the user interface component changes state.

### Expected Results

- #1, #2, and #3 are true.

## Related Techniques

- ARIA4
- H91

## Resources

- Accessible Rich Internet Applications (WAI-ARIA), Roles
- Accessible Rich Internet Applications (WAI-ARIA), The Roles Model
- Accessible Rich Internet Applications (WAI-ARIA), Supported States and Properties
- WAI-ARIA Authoring Practices Guide
- Using WAI-ARIA in HTML