Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

ARIA live regions: status, alert, aria-live, and aria-atomic

ARIA live regions expose content updates to assistive technology without moving focus. Choose the priority of an announcement and how much context it should include.

Version: Current web platform; runtime support varies

Syntax

// Live-region roles and attributes are defined by WAI-ARIA 1.2.
role="status"  (implicit aria-live="polite", aria-atomic="true")
role="alert"   (implicit aria-live="assertive", aria-atomic="true")
aria-live="off" | "polite" | "assertive"
aria-atomic="false" | "true"

// DOM update: change the text of a node in an existing live region.
messageNode.textContent = message;

ARIA live regions (status, alert, aria-live, aria-atomic) let assistive technology such as a screen reader announce content changes without moving focus. These roles and attributes belong to the web platform, not ECMAScript. JavaScript updates the DOM, for example with textContent when the message is plain text.

Use role="status" for non-urgent information such as a result count. It implies aria-live="polite" and aria-atomic="true". The role="alert" role implies aria-live="assertive" and aria-atomic="true". Use it sparingly, only for urgent messages that do not require a response. Don't add redundant aria-live="assertive" to an alert: some setups may announce it twice.

aria-live sets priority: polite waits for a suitable pause, assertive may interrupt the current announcement, and off does not request announcements while focus is outside the region. Updates may still be announced when focus is in the region. aria-atomic sets scope, not priority: true requests the whole region's content, while false requests only the changed nodes. The general default is false, but both roles above imply true.

Put an empty region in the DOM before updating its content, preferably in the initial HTML. Don't move focus to it just to announce a change. Some setups also announce an alert inserted with its text already present, but don't rely on that. Test with the browser and assistive technology combinations you support.

Examples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>ARIA live regions</title>
</head>
<body>
  <button type="button" id="add-result">Add result</button>
  <button type="button" id="simulate-failure">Simulate connection loss</button>
  <p id="result-status" role="status"></p>
  <p id="connection-alert" role="alert"></p>

  <script>
    const statusRegion = document.getElementById('result-status');
    const alertRegion = document.getElementById('connection-alert');
    const count = document.createElement('span');
    let total = 0;

    document.getElementById('add-result').addEventListener('click', () => {
      if (total === 0) statusRegion.append('Results: ', count);
      total += 1;
      count.textContent = String(total);
    });

    document.getElementById('simulate-failure').addEventListener('click', () => {
      alertRegion.textContent = 'Connection lost. Changes cannot be saved.';
    });
  </script>
</body>
</html>

Result

Initially both regions are empty.
After the first activation of Add result: Results: 1
After the second activation of Add result: Results: 2
After activating Simulate connection loss: Connection lost. Changes cannot be saved.
These are visible text updates, not a screen reader transcript.

Save the example as an HTML file and open it in a browser. Activate “Add result” twice, then “Simulate connection loss”. On the second activation only the number changes, but `status` requests the whole message. The output is visible page text, not guaranteed speech.

Related lessons

  • JavaScript · Lesson 23 · Intermediate · Version: 3

Sources