Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README suggestions #3

Merged
merged 2 commits into from
Feb 9, 2024
Merged

README suggestions #3

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
40f9158
Don't hard wrap
khiga8 Feb 9, 2024
21a36ed
Note on default, and using as global live region
khiga8 Feb 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 12 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,36 +4,32 @@

## Getting started

To install `@primer/live-region-element` in your project, you will need to run the
following command using [npm](https://www.npmjs.com/):
To install `@primer/live-region-element` in your project, you will need to run the following command using [npm](https://www.npmjs.com/):

```bash
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:
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:

```ts
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.
The package also provides `announce()` and `announceFromElement` so that you can directly call them, as well.

```ts
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.
Each method also supports specifying the politeness level of the announcement through the `politeness` option.
By default, announcements will be `polite`.

```ts
const liveRegion = document.querySelector('live-region')
Expand All @@ -47,25 +43,19 @@ liveRegion.announce('Example assertive message', {
})
```

It is **essential** that the `live-region` element exists in the initial HTML
payload of your application. To do so, include `<live-region></live-region>` in
your HTML and make sure that [the custom element has been
defined](#defining-live-region-as-a-custom-element). Follow the [Declarative
shadow DOM](#declarative-shadow-dom) section below if you would like to include
this in your HTML.
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](#defining-live-region-as-a-custom-element). Follow the [Declarative shadow DOM](#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.
The `@primer/live-region-element` package provides an entrypoint that you can use to define the `live-region` custom element.

```ts
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:
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:

```ts
import {LiveRegionElement} from '@primer/live-region-element'
Expand All @@ -77,9 +67,7 @@ if (!customElements.get('live-region')) {

### Declarative Shadow DOM

The `live-region` custom element includes support for [Declarative Shadow
DOM](https://developer.chrome.com/docs/css-ui/declarative-shadow-dom) and you
can leverage this feature by using the following snippet:
The `live-region` custom element includes support for [Declarative Shadow DOM](https://developer.chrome.com/docs/css-ui/declarative-shadow-dom) and you can leverage this feature by using the following snippet:

```html
<live-region>
Expand All @@ -100,9 +88,7 @@ can leverage this feature by using the following snippet:
</live-region>
```

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

## 🙌 Contributing

Expand Down
Loading