{"id":28455587,"url":"https://github.com/primer/live-region-element","last_synced_at":"2025-06-27T02:31:42.299Z","repository":{"id":221747723,"uuid":"755272531","full_name":"primer/live-region-element","owner":"primer","description":"A custom element for making announcements with live regions","archived":false,"fork":false,"pushed_at":"2025-06-02T21:15:27.000Z","size":648,"stargazers_count":7,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-06T22:09:46.495Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://primer.github.io/live-region-element/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/primer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-09T19:32:16.000Z","updated_at":"2025-05-05T17:13:38.000Z","dependencies_parsed_at":"2025-01-07T20:19:10.534Z","dependency_job_id":"228b4b60-2df8-4fca-8952-018eb0c65b09","html_url":"https://github.com/primer/live-region-element","commit_stats":null,"previous_names":["primer/live-region-element"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/primer/live-region-element","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primer%2Flive-region-element","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primer%2Flive-region-element/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primer%2Flive-region-element/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primer%2Flive-region-element/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/primer","download_url":"https://codeload.github.com/primer/live-region-element/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primer%2Flive-region-element/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262177664,"owners_count":23270912,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-06T22:09:48.184Z","updated_at":"2025-06-27T02:31:42.287Z","avatar_url":"https://github.com/primer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# live-region-element\n\n\u003e A custom element for making announcements with live regions\n\n## Getting started\n\nTo install `@primer/live-region-element` in your project, you will need to run the following command using [npm](https://www.npmjs.com/):\n\n```bash\nnpm install -S @primer/live-region-element\n```\n\n## Usage\n\nThe `@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:\n\n```ts\nconst liveRegion = document.querySelector('live-region')\n\nliveRegion.announce('Example message')\n```\n\nThe package also provides `announce()` and `announceFromElement` so that you can directly call them, as well.\n\n```ts\nimport {announce, announceFromElement} from '@primer/live-region-element'\n\nannounce('Example message')\n```\n\nEach method also supports specifying the politeness level of the announcement through the `politeness` option.\nBy default, announcements will be `polite`.\n\n```ts\nconst liveRegion = document.querySelector('live-region')\n\nliveRegion.announce('Example polite message', {\n  politeness: 'polite',\n})\n\nliveRegion.announce('Example assertive message', {\n  politeness: 'assertive',\n})\n```\n\nIt 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.\n\nTo do so, include `\u003clive-region\u003e\u003c/live-region\u003e` 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.\n\n### Declarative Shadow DOM\n\nThe `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:\n\n```html\n\u003clive-region\u003e\n  \u003ctemplate shadowrootmode=\"open\"\u003e\n    \u003cstyle\u003e\n      :host {\n        clip-path: inset(50%);\n        height: 1px;\n        overflow: hidden;\n        position: absolute;\n        white-space: nowrap;\n        width: 1px;\n      }\n    \u003c/style\u003e\n    \u003cdiv id=\"polite\" aria-live=\"polite\" aria-atomic=\"true\"\u003e\u003c/div\u003e\n    \u003cdiv id=\"assertive\" aria-live=\"assertive\" aria-atomic=\"true\"\u003e\u003c/div\u003e\n  \u003c/template\u003e\n\u003c/live-region\u003e\n```\n\nIn addition, a `templateContent` export is available through the package which can be used alongside `\u003ctemplate shadowrootmode=\"open\"\u003e` to support this feature.\n\n### Delaying announcements\n\nBoth `announce` and `announceFromElement` provide support for announcing\nmessages at a later point in time. In the example below, we are waiting five\nseconds before announcing the message.\n\n```ts\nimport {announce} from '@primer/live-region-element'\n\nannounce('Example message', {\n  delayMs: 5000,\n})\n```\n\n### Canceling announcements\n\nAny announcements made with `announce` and `announceFromElement` may be\ncancelled. This may be useful if a delayed announcements has become outdated. To\ncancel an announcement, call the return value of either method.\n\n```ts\nimport {announce} from '@primer/live-region-element'\n\nconst cancel = announce('Example message', {\n  delayMs: 5000,\n})\n\n// At some point before five seconds, call:\ncancel()\n```\n\nIf you would like to clear all announcements, like when transitioning between\nroutes, you can call the `clear()` method on an existing `LiveRegionElement`.\n\n```ts\nconst liveRegion = document.querySelector('live-region')\n\n// Send example messages\nliveRegion.announce('Example polite message', {\n  delayMs: 1000,\n  politeness: 'polite',\n})\nliveRegion.announce('Example polite message', {\n  delayMs: 1000,\n  politeness: 'polite',\n})\n\n// Clear all pending messages\nliveRegion.clear()\n```\n\n## 🙌 Contributing\n\nWe're always looking for contributors to help us fix bugs, build new features,\nor help us improve the project documentation. If you're interested, definitely\ncheck out our [Contributing Guide](/.github/CONTRIBUTING.md)! 👀\n\n## License\n\nLicensed under the [MIT License](/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimer%2Flive-region-element","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprimer%2Flive-region-element","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimer%2Flive-region-element/lists"}