User Tools

Site Tools


ARIA: Dynamic States, Live Regions, and Change Announcements

Any change to the user’s page context requires an audible announcement in the screen reader. ARIA dynamic properties should be used when there is a change in the page markup, but the page has not been reloaded. Form validation errors and other announcements to the user should be marked up using ARIA live regions. Search results that refresh automatically should announce their state, both in progress and after the refresh.

Dynamic Properties

These are a few of the most common ARIA component properties. See the Properties tab of the DigitalA11y ARIA Cheat Sheet for a complete list.

The values of these properties can be changed dynamically as the page content is updated.

  • General
    • aria-hidden (boolean, or no value): Removes the element’s contents from screen reader announcements.
    • aria-controls (ID attributes): Lists the elements whose contents or presence are controlled by the current element.
    • aria-owns (ID attributes): Lists child objects, including elements that are not direct descendants of the current object.
    • aria-activedescendant (ID attribute): Identifies the currently active descendant of a composite widget.
    • aria-setsize (number): When a complex component should indicate a count of its total set (like a list), this property can be used to give that count when not all members of the set are in the DOM. Use aria-posinset on each element to give the index of its position in the total set.These attributes are not needed if all elements in the set are present in the DOM when the page finishes loading.
  • Specific components
    • aria-autocomplete (boolean): Indicates whether user input completion suggestions are provided.
    • aria-haspopup (boolean): Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
    • aria-modal (boolean): Indicates whether an element is modal when displayed
    • aria-value* (number): Several properties dealing with the possible and current values of range and number inputs.
    • Tables and grids
      • aria-col and aria-row (number): Several properties describing the total number and span of grid columns and rows
      • aria-sort ("ascending" or "descending"): Indicates whether a column is sorted in ascending or descending order.

The aria-controls and aria-owns properties help associate complex components like autocomplete inputs and their result sets, where parts of the markup may be located in different places in the DOM. When one part of a descendant can be selected or focused, aria-activedescendant identifies the active choice.

Form Static Attributes

  • aria-readonly (boolean, or no value): Indicates that the element is not editable but is otherwise operable.
  • aria-required (boolean, or no value): Indicates that user input is required on the element before a form may be submitted.

ARIA Live Regions

  • aria-live ("off", "polite", or "assertive"): 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. Use with aria-atomic to indicate how much of the enclosed region should be read aloud when the content changes.
  • aria-atomic (boolean): 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.
  • aria-relevant (boolean): Indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified.

Use both aria-live and aria-atomic on any part of the page that should announce changed content to the user. If the entire contents of the region should be read to the user when an update is made, set aria-atomic to true. If only some parts of the enclosed content will change, and those pieces can be contained in child HTML elements of the live region, set aria-atomic to false for the region container and use aria-relevant="true" on each of the descendant elements that have changed.

Note that browser support for aria-atomic is uneven.

Further reading on ARIA Live

accessibility/aria/live.txt · Last modified: 2024/01/22 10:05 by scl

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

© 2008-2022 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a U.S. 501(c)3 non-profit organization.