The HTML aria-relevant attribute
The aria-relevant attribute specifies which kinds of changes in a live region are announced. Values (space-separated): additions, removals, text, or all. The default is additions text.
Overview
The aria-relevant attribute specifies which types of changes in a live region should be announced.
It configures (or relates to) a live region: an area whose dynamic updates are announced to screen-reader users without moving focus. The region must already exist in the DOM before its contents change, and live regions should be used sparingly so a flood of announcements does not overwhelm the user.
Like all ARIA, aria-relevant changes only the accessibility tree (what assistive technology perceives), never the element's behavior or appearance. The first rule of ARIA applies: if a native HTML element or attribute conveys this, use that instead, and only reach for ARIA when nothing native fits.
Syntax
<ul aria-live="polite" aria-relevant="additions"> … </ul>Values
| Value |
|---|
| A space-separated list: additions, removals, text, all. |
Example
<ul aria-live="polite" aria-relevant="additions text"> … </ul>Best practices
- Follow the first rule of ARIA: use a native HTML element or attribute that conveys this where one exists, rather than adding ARIA.
- Put the live region in the DOM first, then change its contents so the update is announced.
- Use polite announcements for most updates; reserve assertive for genuinely urgent ones.
- Use live regions sparingly to avoid overwhelming the user with announcements.