WCAG 4.1.3 Status Messages

Introduction

This document provides information about the Acquia Web Governance accessibility check:

• Are status messages presented clearly to assistive technology users?

What

Status messages provide important information to users about the outcome of an action, system status updates, or changes in content. These messages must be programmatically determinable. Assistive technologies such as screen readers must be able to detect and announce the messages without requiring users to manually shift focus. This success criteria states that website owners must make users aware of important changes in content. 

A status message does not receive focus. However, it must be conveyed to users who rely on assistive technologies such as screen readers. This is especially important for:

• Error messages: This includes form validation errors.
• Success confirmations: This includes messages such as: The form has been submitted successfully.
• Loading indicators: This includes informational indications such as the message: Loading results... on search filters.

To achieve this, status messages must be properly marked up with ARIA roles and properties, such as:

• role="status"
  • Used for general updates.
• aria-live="polite" or aria-live="assertive"
  • Used to announce changes dynamically.
• aria-atomic="true"
  • Used to ensure that the full message is announced when it is updated.

Why

This section provides information about why this check is important and which users are affected. In addition, it provides some examples.

Why are status messages important?

Users who are blind or have low vision rely on screen readers to understand dynamic changes on a webpage. If status messages are not programmatically determined, the screen reader software may fail to detect and announce updates.

Who

Affected users

This check primarily affects users who:

• Are blind or have low vision, as they rely on screen readers to perceive content.
• Have cognitive disabilities, as they can become confused by unexpected content changes without notification.

Without accessible status messages, users may not be aware of:

• Errors or validation failures.
• System messages such as Your changes have been saved.
• Dynamically-loaded content updates, such as search results that appear without a full page reload.
• Screen reader users: Who may miss important updates if the messages are not announced.
• Users with cognitive disabilities: Who may require additional context for dynamic updates.

Examples

This section provides some pass and fail examples of this check.

Pass examples

• Using aria-live for dynamically updating content

  copy

  <p id="statusMessage" aria-live="polite">Your changes have been saved.</p>
  <script>
    function saveData() {
      document.getElementById("statusMessage").textContent = "Your data has been successfully saved!";
    }
  </script>
  <button onclick="saveData()">Save</button>

  • Why is this correct?
    • The <p> element has aria-live="polite", which tells assistive technologies to announce changes dynamically.
    • Users who rely on screen readers can hear the update and they will not have to navigate to it manually.

• Using role="status" to indicate a status update

  copy

  <p role="status">Your message has been sent.</p>

  • Why is this correct?
    • The role="status" attribute automatically announces the message to screen reader users when the text is updated.

Fail examples

• No programmatic indication of status updates

  copy

  <p>Your form has been submitted.</p>

  • Issue: Without aria-live="polite" or role="status", a screen reader user may never hear this message.

• A JavaScript alert() instead of an aria-live region

  copy

  <script>
    function showAlert() {
      alert("Your form has been submitted!");
    }
  </script>
  <button onclick="saveData()">Submit</button>

  • Issue: alert() shifts focus away from the current position and can interrupt the workflow.
  • Solution: Use an aria-live region.

How

This section provides instructions on how to review and fix this issue.

How to review it

• Identify dynamic messages
  • Look for updates such as:
    • Form submission confirmations
    • Live chat notifications
    • Error or success messages
    • Changes in shopping cart contents
    • Auto-suggestions in search fields.
• Ensure that assistive technologies can detect updates
  • Use a screen reader such as NVDA, JAWS, or VoiceOver.
  • Trigger a few status changes and listen for announcements.
• Verify that ARIA attributes are present
  • Open Developer Tools, this is the F12 function in most browsers.
    • Locate the element that displays the status message.
    • Ensure that the element contains attributes such as role="status", aria-live="polite", or aria-live="assertive".
  • Ensure that the text in these elements is updated when the status changes.

How to fix it

• Identify all status messages on your website. This includes form submission confirmations, error messages, and real-time updates.
  • Ensure they have the proper ARIA attributes such as: role="status", aria-live="polite", or aria-atomic="true" so that the screen reader software can announce them automatically.
  • Use CSS for styling, not structure. If you only use a <p> element without ARIA attributes, screen reader users do not hear the update.
• Do a test with a screen reader. Confirm that status messages are announced and do not require user focus.
• Check the attributes and ensure that the following examples are used when appropriate:
  • Use role="alert" for urgent updates
  • copy

    <p role="alert">Error: Please enter a valid email address.</p>

    • The role="alert" attribute ensures that the message is immediately announced by screen readers and does not move focus.

  • Use aria-live="polite" for non-urgent status messages

    copy

    <p id="statusMessage" aria-live="polite">Your message has been sent.</p>
    <script>
      function sendMessage() {
        document.getElementById("statusMessage").textContent = "Your message has been sent.";
      }
    </script>
    <button onclick="sendMessage()">Send Message</button>

    • The aria-live="polite" attribute ensures that screen reader software announces the message and does not interrupt users.

• Mark up status messages with ARIA roles and properties, such as:

  • Use role="status"  for general updates.
  • Use aria-live="polite" or aria-live="assertive" to announce changes dynamically.
  • Use aria-atomic="true" to ensure that the full message is announced when it is updated.

Additional resources

WCAG success criteria

WCAG 4.1.3 Status Messages

Are status messages presented clearly to assistive technology users?