useKLiveRegion link to current page

pull/1114 | Release notes

Overview
#

A composable that offers sendPoliteMessage and sendAssertiveMessage functions that send polite and assertive messages to their corresponding ARIA live regions.

When to use live regions
#

Before sending messages to live regions, always research carefully if you really need it for the task ahead. Live regions can be buggy and inconsistent. There are often better alternatives, such as utilizing WAI-ARIA attributes. A good rule of thumb is to use live regions only when there's no other way.

Usage
#

Since polite and assertive regions are inserted to an application's document body automatically during the KDS installation process , the only thing you need to do to deliver messages is to import and call sendPoliteMessage or sendAssertiveMessage from any place in your application.

These two methods are also used internally from some KDS components to provide a11y out of the box. Always check that you don't send messages to announce updates that are already being announced from KDS to prevent from duplicate announcements.

Polite message

Sending a polite message updates the text content of aria-live="polite" region. Use it to send messages that can wait to be announced until the user is idle. This message should typically be the most commonly used.

Send polite messages with sendPoliteMessage(message):


      import useKLiveRegion from 'kolibri-design-system/lib/composables/useKLiveRegion';

      export default {
        setup() {
          const { sendPoliteMessage } = useKLiveRegion();
          sendPoliteMessage('Polite message');
        }
      };

Assertive message

Sending an assertive message updates the text content of aria-live="assertive" region. Use this only for messages that require immediate attention, such as critical errors or messages, as it interrupts the user's current activity.

For errors or updates that need immediate user action, make sure that related elements (e.g., buttons) are in focus right after the message has been read by the screen reader, so users can act on them.

Send assertive messages with sendAssertiveMessage(message):


      import useKLiveRegion from 'kolibri-design-system/lib/composables/useKLiveRegion';

      export default {
        setup() {
          const { sendAssertiveMessage } = useKLiveRegion();
          sendPoliteMessage('Assertive message');
        }
      };

Demo
#

Send messages below and turn on your screen reader. You could also observe the content of <div id="k-live-region"> in the browser console, but note that an announcement will be visible for just a very brief moment.

 
 

Related
#