useKLiveRegion link to current page

develop | 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. It should be used with caution because it disrupts the user's flow. Use it only to send messages that require immediate attention, such as errors.

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
#