@primer/live-region-element

live-region-element

A custom element for making announcements with live regions

Getting started

To install @primer/live-region-element in your project, you will need to run the following command using npm:

npm install -S @primer/live-region-element

Usage

The @primer/live-region-element package provides a custom element to assist in making announcements with live regions. You can make announcements with this custom element by calling the announce() and announceFromElement methods:

const liveRegion = document.querySelector('live-region')

liveRegion.announce('Example message')

The package also provides announce() and announceFromElement so that you can directly call them, as well.

import {announce, announceFromElement} from '@primer/live-region-element'

announce('Example message')

Each method also supports specifying the politeness level of the announcement through the politeness option. By default, announcements will be polite.

const liveRegion = document.querySelector('live-region')

liveRegion.announce('Example polite message', {
  politeness: 'polite',
})

liveRegion.announce('Example assertive message', {
  politeness: 'assertive',
})

It is essential that the live-region element exists in the initial HTML payload of your application. Having multiple live regions on a page is discouraged so we recommend having a single global live region that is available across every page of your application by embedding this live-region element as part of your page layout.

To do so, include <live-region></live-region> in your HTML and make sure that the custom element has been defined. Follow the Declarative shadow DOM section below if you would like to include this in your HTML.

Defining live-region as a custom element

The @primer/live-region-element package provides an entrypoint that you can use to define the live-region custom element.

import '@primer/live-region-element/define`

If you prefer to define the custom element directly, import LiveRegionElement directly from the package and use that to define the live-region element. For example:

import {LiveRegionElement} from '@primer/live-region-element'

if (!customElements.get('live-region')) {
  customElements.define('live-region', LiveRegionElement)
}

Declarative Shadow DOM

The live-region custom element includes support for Declarative Shadow DOM and you can leverage this feature by using the following snippet:

<live-region>
  <template shadowrootmode="open">
    <style>
      :host {
        clip-path: inset(50%);
        height: 1px;
        overflow: hidden;
        position: absolute;
        white-space: nowrap;
        width: 1px;
      }
    </style>
    <div id="polite" aria-live="polite" aria-atomic="true"></div>
    <div id="assertive" aria-live="assertive" aria-atomic="true"></div>
  </template>
</live-region>

In addition, a templateContent export is available through the package which can be used alongside <template shadowrootmode="open"> to support this feature.

🙌 Contributing

We're always looking for contributors to help us fix bugs, build new features, or help us improve the project documentation. If you're interested, definitely check out our Contributing Guide! 👀

License

Licensed under the MIT License.