accessibility-guidelines

This document is in beta. Help us by reporting issues via Github or email

Back to the overview page

Status messages

On this page:

• Summary
• Requirements
• Guidance for Design
• Guidance for iOS
• Guidance for Android
• Guidance for Flutter
• Guidance for Web
• More info

---

Summary

Make sure status messages are identified in code, so that assistive technologies can convey them to users.

Requirements

There are different situations where a status message need to be shown in a way that screen readers understand. For example:

• error messages that appear while users fill in a form;
• an alert message that is displayed when a session is about to expire;
• some content that is changed/removed/added as a result of a user’s action.

These messages need to be conveyed to users without disturbing the user’s position on a page.

Screen reader announcements (using ARIA Live regions for the Web, for example) should be used to inform screen reader users of these events without disrupting their position on the page.

Why?

• A sighted person can quickly see status messages on a page, and them go back to what they were doing or reading. Moving focus to a message can be disruptive for screen reader users, users of speech recognition software and keyboard only users.
  • Screen reader users navigate page with what is called a ‘screen reader cursor’. They can move that screen reader cursor using their keyboard, braille display or gestures on a touch screen.
  • Status messages (like system error messages or form validation error messages) need to be communicated to users without moving their ‘scren reader cursor’ on the page. Otherwise users would need to figure out where they are on the page afterwards, and move back to where they wanted to be.
• If focus is always moved to the message users with cognitive impairments may also be confused by unpredictable focus changes.

Official wording in the Web Content Accessibility Guidelines

4.1.3 Status Messages: In content implemented using markup languages, status messages can be programmatically determined through role or properties such that they can be presented to the user by assistive technologies without receiving focus. (Level AA)

See the W3C’s detailed explanation of this guideline with techniques and examples.

---

Guidance for Design

This section needs more content. Contribute via Github or email.

---

Guidance for iOS

This section needs more content. Contribute via Github or email.

---

Guidance for Android

You can use a live region in order to send a new AccessibilityEvent to the current enabled Accessibility Service on view updates. This means that any service like TalkBack will pay attention to any changes in that View and will automatically announce them.

To do so, you can easily mark any View as a live region in your XML file by adding the accessibilityLiveRegion attribute:

<View
  ...
  android:accessibilityLiveRegion="polite"
  .../>

Options for this attribute are the following:

• none: Accessibility services should not announce changes to this view.
• polite: Accessibility services should announce changes to this view.
• assertive: Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

Carefully consider when to use live regions, as announcements for frequently changing views can be disruptive and annoying. Live regions can easily be overused, especially when you’re just starting out with accessibility. Live regions are the exception, not the rule.

---

Guidance for Flutter

Widgets with built in error messages such as TextField() in a Form() widget have their errors read out automatically when the validator: (value) {} returns a error string.

The same can be said for the AlertDialog widget.

• If you want the screen reader to read something out programmatically, for example on a state change or a widget coming into view you can use:

  SemanticsService.announce( String, TextDirection.ltr); // the text direction should be based on some sort of localization setting.
  

---

Guidance for Web

The following are different situations you will need to cover:

When a status message tells the user something is successful

When a status message tells the user something is successful or is the results of an action. This can also be used for a state change when part of a page updates:

You can use these following techniques:

Use the ARIA role=”status” to present status messages in combination with the technique Providing success feedback when data is submitted successfully.

If a status message conveys a suggestion, or a warning or error:

NOTE: There may be times when the best user experience is to move focus to a message, such as an error, as a part of form validation etc. See the GDS’ Error Summary component and guidance for an example.

Use the following techniques:

Use ARIA role=”alert” or Live Regions to Identify Errors in combination with any of the following:

• Providing text descriptions to identify required fields that were not completed
• Providing a text description when the user provides information that is not in the list of allowed values
• Providing a text description when user input falls outside the required format or values
• Creating a mechanism that allows users to jump to errors
• Providing suggested correction text
• Providing spell checking and suggestions for text input

If a status message conveys information on the progress of a process:

The ARIA role="progressbar" can be used but may not be enough on its own (depending on support by browsers and assistive technologies). For some examples of progressbar role see:

• Mozilla - Using the progressbar role
• ARIA Progress bar example - LevelAccess Labs

You can use the following techniques:

• Using role=log to identify sequential information updates
• Using role=status to present status messages in combination with Providing help by an assistant in the Web page

Common mistakes

• Status messages are not to be shown in a way that the screen reader understands and without receive keyboard focus.
• Using role="alert" or aria-live="assertive" on content which is not important.
• On a page with ARIA live regions - if regions are hidden or not needed - always make sure to switch their active and inactive states accordingly.

More guidance for Web

• ARIA live regions article on MDN

---

More info

Sources

• W3C Web Content Accessibility Guidelines 2.1
• Government Digital Service WCAG 2.1 Primer
• Barclays’ Accessibility Design Standards

Contribute

This document is in beta. Help us by reporting issues via Github or email

This site is open source. Improve this page.