useKLiveRegion link to current page

pull/1217 | Release notes

Overview
#

#k-live-region element with global polite and assertive live regions is inserted to an application's document body during the KDS installation process . useKLiveRegion provides an easy and reliable way to send messages to them from any place in the application. It is built with best practices in mind to prevent messages from getting lost, conflicting with each other, and other common pitfalls.

Guidelines
#

  • Consider carefully if you really need to use a live region. Despite all best practices, live regions can still be buggy and inconsistent. There are often better alternatives, such as utilizing WAI-ARIA attributes.
  • Do not manually insert any live regions (e.g. via aria-live, role="alert", ...). Multiple live regions or live regions nested deep in the DOM structure are problematic. Always use useKLiveRegion.
  • Use assertive messages only for critical information that requires immediate attention.
  • 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.
  • Ensure that messages are translated, concise and provide useful information.
  • Some KDS components already send announcements. Always check that you don't send messages that are already being announced from KDS to prevent from duplicate announcements.

Usage
#

To deliver messages to the global live regions, call sendPoliteMessage or sendAssertiveMessage from any place in your application.

Polite message

Sending a polite message updates the text content of the global 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. 


      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.


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

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

Example
#

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
#