diff --git a/files/en-us/web/accessibility/aria/guides/live_regions/index.md b/files/en-us/web/accessibility/aria/guides/live_regions/index.md index 21f35e67e404fc4..2356a39a80fdc0f 100644 --- a/files/en-us/web/accessibility/aria/guides/live_regions/index.md +++ b/files/en-us/web/accessibility/aria/guides/live_regions/index.md @@ -259,3 +259,4 @@ Breakdown of ARIA live properties: ## See also - [ARIA roles](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles) +- {{domxref("Document.ariaNotify()")}}, {{domxref("Element.ariaNotify()")}} diff --git a/files/en-us/web/accessibility/aria/reference/attributes/aria-live/index.md b/files/en-us/web/accessibility/aria/reference/attributes/aria-live/index.md index 720e0f9857e77b3..4cb8db502e83719 100644 --- a/files/en-us/web/accessibility/aria/reference/attributes/aria-live/index.md +++ b/files/en-us/web/accessibility/aria/reference/attributes/aria-live/index.md @@ -88,3 +88,4 @@ Used in **ALL** roles. - [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-relevant) - [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) - [`alert` role](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) +- {{domxref("Document.ariaNotify()")}}, {{domxref("Element.ariaNotify()")}} diff --git a/files/en-us/web/api/document/arianotify/index.md b/files/en-us/web/api/document/arianotify/index.md new file mode 100644 index 000000000000000..723de3a61bf7630 --- /dev/null +++ b/files/en-us/web/api/document/arianotify/index.md @@ -0,0 +1,299 @@ +--- +title: "Document: ariaNotify() method" +short-title: ariaNotify() +slug: Web/API/Document/ariaNotify +page-type: web-api-instance-method +browser-compat: api.Document.ariaNotify +--- + +{{ApiRef("DOM")}} + +The **`ariaNotify()`** method of the {{domxref("Document")}} interface specifies that a given string of text should be announced by a {{glossary("screen reader")}} if available and activated. + +## Syntax + +```js-nolint +ariaNotify(announcement) +ariaNotify(announcement, options) +``` + +### Parameters + +- `announcement` + - : A string specifying the text to be announced. +- `options` {{optional_inline}} + - : An options object containing the following properties: + - `priority` + - : An enumerated value specifying the priority of the announcement. Possible values are: + - `normal` + - : The announcement has normal priority. It will be spoken after any announcement that a screen reader is currently making. + - `high` + - : The announcement has high priority. It will be spoken immediately, interrupting any announcement that a screen reader is currently making. + +### Return value + +None ({{jsxref("undefined")}}). + +## Description + +The **`ariaNotify()`** method can be used to programmatically trigger a screen reader announcement. This method provides similar functionality to [ARIA live regions](/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions), with some advantages: + +- Live regions can only make announcements following changes to the DOM, whereas an `ariaNotify()` announcement can be made at any time. +- Live region announcements involve reading out the updated content of the changed DOM node, whereas `ariaNotify()` announcement content can be defined independently of DOM content. + +Developers often work around the limitations of live regions using hidden DOM nodes with live regions set on them, which have their contents updated with the content to be announced. This is inefficient and error-prone, and `ariaNotify()` provides a way to avoid such issues. + +Some screen readers will read out multiple `ariaNotify()` announcments in order, but this cannot be guaranteed across all screen readers and platforms. Normally, only the most recent announcement is spoken. It is more reliable to combine multiple announcements into one. + +For example, the following calls: + +```js +document.ariaNotify("Hello there."); +document.ariaNotify("The time is now 8 o'clock."); +``` + +would be better combined: + +```js +document.ariaNotify("Hello there. The time is now 8 o'clock."); +``` + +`ariaNotify()` announcements do not require {{glossary("transient activation")}}; you should take care not to spam screen reader users with too many notifications, as this could create a bad user experience. + +### Announcement priorities + +An `ariaNotify()` announcement with `priority: high` set is announced before an `ariaNotify()` announcement with `priority: normal` set. + +`ariaNotify()` announcements are roughly equivalent to ARIA live region announcements as follows: + +- `ariaNotify()` `priority: high`: `aria-live="assertive"`. +- `ariaNotify()` `priority: normal`: `aria-live="polite"`. + +However, `aria-live` announcements will take priority over `ariaNotify()` announcements. + +### Language selection + +Screen readers choose an appropriate voice with which to read `ariaNotify()` announcements (in terms of accent, pronounciation, etc.) based on the language specified in the {{htmlelement("html")}} element's [`lang`](/en-US/docs/Web/HTML/Reference/Global_attributes/lang) attribute, or the user agent's default language if no `lang` attribute is set. + +### Permissions policy integration + +Usage of `ariaNotify()` in a document or {{htmlelement("iframe")}} can be controlled by an {{httpheader("Permissions-Policy/aria-notify", "aria-notify")}} [Permission Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy). + +Specifically, where a defined policy blocks usage, any announcements created using `ariaNotify()` silently fail (they will not be sent). + +## Examples + +### Basic `ariaNotify()` usage + +This example includes a {{htmlelement("button")}} that fires a screen reader announcement when clicked. + +```html live-sample___basic-arianotify + +``` + +```css hidden live-sample___basic-arianotify +html, +body { + height: 100%; +} + +body { + display: flex; + justify-content: center; + align-items: center; +} +``` + +```js live-sample___basic-arianotify +document.querySelector("button").addEventListener("click", () => { + document.ariaNotify("Hi there, I'm Ed Winchester."); +}); +``` + +#### Result + +The output is as follows: + +{{EmbedLiveSample("basic-arianotify", "100%", 60, , , , "aria-notify")}} + +Try activating a screen reader and then pressing the button. You should hear "Hi there, I'm Ed Winchester." spoken by the screen reader. + +### Accessible shopping list example + +This example is a shopping list that allows you to add and remove items, and keeps track of the total cost of all items. When an item is added or removed, screen readers will read out an announcement to say what item was added/removed, and what the updated total is. + +#### HTML + +Our HTML features a {{htmlelement("form")}} containing two {{htmlelement("input")}} elements — one `text` input to enter item names into, and one `number` input to enter prices into. Both inputs are [`required`](/en-US/docs/Web/HTML/Reference/Attributes/required), and the `number` input has a [`step`](/en-US/docs/Web/HTML/Reference/Attributes/step) value of `0.01` to stop non-price values (like large decimals) being entered. + +Below the form we have an [unordered list](/en-US/docs/Web/HTML/Reference/Elements/ul) to render added items in, and a {{htmlelement("p")}} element to display the total cost. + +```html live-sample___shopping-list +
ariaNotify demo: shopping listTotal: £0.00
+``` + +```css hidden live-sample___shopping-list +html { + box-sizing: border-box; + font: 1.2em / 1.5 system-ui; +} + +body { + width: 600px; + margin: 0 auto; +} + +form { + padding: 0 50px; +} + +div { + display: flex; + margin-bottom: 20px; +} + +label { + flex: 2; +} + +input { + flex: 4; + padding: 5px; +} + +form button { + padding: 5px 10px; + font-size: 1em; + border-radius: 10px; + border: 1px solid gray; +} + +li { + margin-bottom: 10px; +} + +li button { + font-size: 0.6rem; + margin-left: 10px; +} +``` + +#### JavaScript + +Our script starts with several constant definitions to store references to the `