Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@primer/live-region-element

Package Overview
Dependencies
Maintainers
11
Versions
12
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@primer/live-region-element

> A custom element for making announcements with live regions

  • 0.5.0
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
19K
increased by22.76%
Maintainers
11
Weekly downloads
 
Created
Source

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.

FAQs

Package last updated on 02 Apr 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc