Live region roles

Hey ,

I'm thrilled to help you learn JavaScript. Unfortunately, you've landed on a page where you cannot access with your current purchase.

Please upgrade (use this link) access this content.

I'm super eager to help you learn more!

Live region roles

Live regions are special.

When something changes on a webpage, a sighted user can see what changed. But a blind user can’t. Live regions exist to tell blind users what has changed. They announce the changes.

There are five live region roles:

1. alert
2. status
3. log
4. marquee
5. timer

Explanation of each role

Alert contains messages important and time-sensitive messages. One example is error messages. You should not use alert unless the messages are important AND time-sensitive.

<div role="alert"> ... </div>

Status tells the user something has changed. This contains information that’s not important to warrant an alert.

<div role="status"> ... </div>

Log is used for regions where information is added in a meaningful order. It can be used for things like chat logs or game logs. Old information may be removed from logs.

<div role="log"> ... </div>

Marquee is used for non-essential information that changes regularly. An example is a stock ticker.

<div role="marquee"> ... </div>

Timer is used for any kind of timer or clock.

<div role="timer"> ... </div>

You only need to use alert and status to make most components screen-reader accessible. There’s no need for log, marquee, or timer.

Live-region roles and live-region attributes

Each live region role is paired with live region attributes. Here are the pairings:

aria-live and aria-atomic are live-region related aria-properties/states. I’m going to call them live-region attributes to make it easier on the ears

Live-region attributes

There are four live-region attributes:

1. aria-live
2. aria-atomic
3. aria-relevant
4. aria-busy

You don’t need to use these attributes most of the time. (alert and status roles are enough). But I’ll still explain what each attribute does for the sake of completeness.

Explanation of live-region attributes

Aria-live tells screen readers when to mention changes. It can be set to assertive, polite, or off:

• assertive: Announce changes immediately
• polite: Queue changes and announces them when the next opportunity arises
• off: Don’t announce changes

If you set aria-live to assertive, it’s almost the same as setting role to alert.

<div aria-live="assertive"> ... </div>

Aria-atomic tells screen readers what the nodes it should mention when something changes. It can be true or false.

• true: Announces the entire live region
• false: Announces only the changed node in the live region.

<div aria-atomic="true"> ... </div>

Aria-relevant tells screen readers what kind of changes to mention. It is a space delimited list that can contain these four values:

• additions: Only announce when things are added to the live region
• removals: Only announce when things get removed from the live region
• text: Only announce when text was changed
• all: Announce all changes

aria-relevant defaults to additions text.

<div aria-relevant="additions text"></div>

Aria-busy tells screen readers whether the live region is still being updated. It can be set to true or false.

• true: Screen readers should wait until aria-busy is set to false before announcing changes.

<div aria-busy="true"></div>

Example

In this example, you’ll see Voiceover announce the changes in the <div> with an alert role.

<div role="alert"></div>

<form>
  <label for="input"> Text to announce </label>
  <input type="text" id="input">
  <button> Add text to live region </button>
</form>

const form = document.querySelector('form')
const input = form.querySelector('input')
const alertRegion = document.querySelector('[role="alert"]')

form.addEventListener('submit', event => {
  event.preventDefault()
  const text = input.value.trim()
  alertRegion.textContent = text
})

What you should know:

You only need to know two things:

1. The alert role
2. The status role

Remember them yet? Good. You can discard the rest.

That’s it!