From bef47fb530b8502ce93113d6709b2ba7e273c555 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Fri, 3 May 2019 16:28:01 +0200 Subject: [PATCH 01/14] Guideline for live regions --- live-regions.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 live-regions.md diff --git a/live-regions.md b/live-regions.md new file mode 100644 index 0000000000..701bd0fb4c --- /dev/null +++ b/live-regions.md @@ -0,0 +1,101 @@ +# Live Regions + +Live regions are perceivable regions of a web page that are typically updated as a result of an external event when user focus might be elsewhere. These regions are not always updated as a result of a user interaction. By marking such elements as live regions, users of assistive technology can be informed of the updated content automatically. + +Examples of live regions are a chat log and an error message. However, different kinds of live regions have different expected behavior; users might expect an error message to disrupt what they are doing, since the error is important, but want to wait with reading new chat messages until they are done typing their own message. + +## Live Region States and Properties + +ARIA has the following attributes mark up live regions. + +### `aria-live` + +The `aria-live` attribute indicates that an element is a live region. Some roles implicitly set `aria-live`; this is discussed in a later section. + +* `assertive`: assistive technologies can interrupt the user to provide this information. +* `polite`: assistive technologies will provide this information after the user is done with their current task. +* `off`: assistive technologies will not provide this information unless this region has focus. + +With the exception of a few roles, the default value of `aria-live` is `off`. + +TODO example + +### `aria-relevant` + +Dynamic content changes in a live region is sometimes significant, and sometimes not, depending on the kind of live region. For example, a disappearing old message in a chat log is not significant, and users do not need to be informed of the removal. However, for a list of online contacts, a disappearing contact is significant (it indicates that the contact is no longer online). + +The `aria-relevant` attribute can be used to inform assistive technologies about which kinds of changes are relevant to inform users about. It takes a list of keywords, with the following meanings: + +* `additions`: Element node additions +* `text`: Text or text alternative additions +* `removals`: Text content, text alternative, or element node removals +* `all`: Synonym to `additions removals text` + +If `aria-relevant` is not specified, then the value of the closest ancestor element with an `aria-relevant` attribute is used. Specifying the `aria-relevant` attribute on an element overrides any value specified on an ancestor element. If there is no ancestor element with an `aria-relevant` attribute, the default value `additions text` is used. + +TODO example + +### `aria-atomic` + +The `aria-atomic` attribute takes the values "true" and "false". The attribute can also be omitted. + +When this attribute is set to `true`, assistive technologies will render the element as a whole, and not just parts that have been changed. + +When this attribute is set to `false`, assistive technologies will only render the changes (as per `aria-relevant`) to the user. + +When this attribute is omitted, the user agent will use the closest ancestor that has `aria-atomic` set to `true` or `false`, or if there is no such ancestor, `false`. + +### `aria-busy` + +Sometimes, it takes some time for a script to update the content of a live region. For example, it could be waiting on a network response. In order to avoid rendering half-baked content to users of assistive technology, the `aria-busy` attribute can be set to `true` while the content is being updated, and then to `false` when it is done. + +TODO example + +## Special Case Live Regions + +The roles listed below implicitly set the `aria-live` attribute to indicate that it is a live region. When using these roles, the `aria-live` attribute can be omitted, or it can be specified to change the value from the default. + +### `alert` + +The `alert` role indicates important, usually time-sensitive, information. Use this role when focus is not moved to the message, and the user is not expected to close the message. For an alert dialog that can be closed, the the `alertdialog` role instead. + +The default value for `aria-live` is `assertive`. The default value for `aria-atomic` is `true`. + +TODO example + +### `log` + +The `log` role indicates that new information is added in meaningful order and old information might disappear. + +The default value for `aria-live` is `polite`. + +TODO example + +### `status` + +The `status` role indicates that content is advisory information for the user but is not important enough to justify an `alert`, often but not necessarily presented as a status bar. + +Do not move focus to the element when the content is changed. + +The default value for `aria-live` is `polite`. The default value for `aria-atomic` is `true`. + +TODO example + +### `timer` + +The `timer` role is a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point. + +The `timer` role is a subclass of the `status` role. The default value of `aria-live` value of `off`. + +Update the text content of the element to the current time measurement when it changes. + +TODO example + +### `marquee` + +The `marquee` role indicates non-essential information that changes frequently. + +The default value of `aria-live` value of `off`. + +TODO example (stock ticker) + From f31d6ea02d47a146138cb3830ffc33039b802e92 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 6 May 2019 19:59:07 +0200 Subject: [PATCH 02/14] Add examples --- live-regions.md | 97 +++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 85 insertions(+), 12 deletions(-) diff --git a/live-regions.md b/live-regions.md index 701bd0fb4c..c09f56c8f5 100644 --- a/live-regions.md +++ b/live-regions.md @@ -12,13 +12,29 @@ ARIA has the following attributes mark up live regions. The `aria-live` attribute indicates that an element is a live region. Some roles implicitly set `aria-live`; this is discussed in a later section. -* `assertive`: assistive technologies can interrupt the user to provide this information. +* `assertive`: assistive technologies can interrupt the user to provide this information, but will not move the current focus, so the user's work flow is not interrupted. * `polite`: assistive technologies will provide this information after the user is done with their current task. * `off`: assistive technologies will not provide this information unless this region has focus. With the exception of a few roles, the default value of `aria-live` is `off`. -TODO example +For example, when the user types into a search field, the page could update the page with search results as the user is typing. To inform users of assistive technology that this has happened, a polite live region can be used. When the user is done typing, and the search is complete, the user is informed of how many results were found, without having to move focus away from the search field. + +``` +
+ + +
+
+ +``` ### `aria-relevant` @@ -33,7 +49,17 @@ The `aria-relevant` attribute can be used to inform assistive technologies about If `aria-relevant` is not specified, then the value of the closest ancestor element with an `aria-relevant` attribute is used. Specifying the `aria-relevant` attribute on an element overrides any value specified on an ancestor element. If there is no ancestor element with an `aria-relevant` attribute, the default value `additions text` is used. -TODO example +For example, a list of online contacts could use `aria-live="all"`: + +``` +
+

Contacts

+ +
+``` +When a contact comes online, it is added to the list, and users of assistive technology are informed of the addition without disrupting their current task. Similarly when a user goes offline. If a contact changes their display name, the text change would also be announced. ### `aria-atomic` @@ -45,11 +71,39 @@ When this attribute is set to `false`, assistive technologies will only render t When this attribute is omitted, the user agent will use the closest ancestor that has `aria-atomic` set to `true` or `false`, or if there is no such ancestor, `false`. +For example, consider a clock that can be set to notify the user of the current time at a regular interval. Without `aria-atomic`, the assistive technology might only notify the changed components, rather than the full time. + +``` +
+ The time is + 16:34:05 +
+``` + ### `aria-busy` Sometimes, it takes some time for a script to update the content of a live region. For example, it could be waiting on a network response. In order to avoid rendering half-baked content to users of assistive technology, the `aria-busy` attribute can be set to `true` while the content is being updated, and then to `false` when it is done. -TODO example +Consider again the search form from the earlier example. When the user starts typing a new search into the search field, the script would update the search results live region, and maybe update multiple times as new search results appear, but it would be a better experience for users of assistive technology to only be notified when the new search is complete. + +``` +
+ + +
+
+ +``` ## Special Case Live Regions @@ -61,7 +115,7 @@ The `alert` role indicates important, usually time-sensitive, information. Use t The default value for `aria-live` is `assertive`. The default value for `aria-atomic` is `true`. -TODO example +See the [Alert design pattern](#alert) and the related [Alert Example](https://w3c.github.io/aria-practices/examples/alert/alert.html). ### `log` @@ -69,17 +123,32 @@ The `log` role indicates that new information is added in meaningful order and o The default value for `aria-live` is `polite`. -TODO example +For example, a chat log would be an appropriate use case for the `log` role. + +``` +
+

[10:26] <Charl> ok let's test it and see if it works

+

[10:59] <hsivonen> morning

+
+``` ### `status` The `status` role indicates that content is advisory information for the user but is not important enough to justify an `alert`, often but not necessarily presented as a status bar. -Do not move focus to the element when the content is changed. - The default value for `aria-live` is `polite`. The default value for `aria-atomic` is `true`. -TODO example +Do not move focus to the element with script when the content is changed. + +For example, the search result summary example above could use `role="status"` instead of `role="region"`: + +``` +
+ + +
+
+``` ### `timer` @@ -89,7 +158,12 @@ The `timer` role is a subclass of the `status` role. The default value of `aria- Update the text content of the element to the current time measurement when it changes. -TODO example +For example, a countdown to New Year could use `role="timer"`. + +``` +

New Year Countdown

+

2 minutes, 51 seconds

+``` ### `marquee` @@ -97,5 +171,4 @@ The `marquee` role indicates non-essential information that changes frequently. The default value of `aria-live` value of `off`. -TODO example (stock ticker) - +For example, a stock ticker that is crawling across the screen could use `role="marquee"`. From 247f576d8ed094b9e1dd1742e476ba50ad0cf08f Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 16:16:22 +0200 Subject: [PATCH 03/14] Add accessible names where required, add an example for marquee --- live-regions.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/live-regions.md b/live-regions.md index c09f56c8f5..5001a4b935 100644 --- a/live-regions.md +++ b/live-regions.md @@ -126,7 +126,8 @@ The default value for `aria-live` is `polite`. For example, a chat log would be an appropriate use case for the `log` role. ``` -
+

IRC Log

+

[10:26] <Charl> ok let's test it and see if it works

[10:59] <hsivonen> morning

@@ -161,8 +162,8 @@ Update the text content of the element to the current time measurement when it c For example, a countdown to New Year could use `role="timer"`. ``` -

New Year Countdown

-

2 minutes, 51 seconds

+

New Year Countdown

+

2 minutes, 51 seconds

``` ### `marquee` @@ -172,3 +173,12 @@ The `marquee` role indicates non-essential information that changes frequently. The default value of `aria-live` value of `off`. For example, a stock ticker that is crawling across the screen could use `role="marquee"`. + +``` +
+

Goosoft $8.24 +0.36

+

Microle $35.60 −0.78

+

Banana $12.30 +0.09

+
+``` +``` From c67c3b83968624028a827de0080ad0c604cedbd9 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 16:20:25 +0200 Subject: [PATCH 04/14] Typo --- live-regions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/live-regions.md b/live-regions.md index 5001a4b935..c2c53e54e6 100644 --- a/live-regions.md +++ b/live-regions.md @@ -181,4 +181,3 @@ For example, a stock ticker that is crawling across the screen could use `role="

Banana $12.30 +0.09

``` -``` From 828bddbc79f12a9338f1779a1f2713f34c6d6fc2 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Fri, 30 Aug 2019 11:35:58 +0200 Subject: [PATCH 05/14] Clarify aria-relevant and point to the new Accessibility tree section --- live-regions.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/live-regions.md b/live-regions.md index c2c53e54e6..afe7195d29 100644 --- a/live-regions.md +++ b/live-regions.md @@ -42,9 +42,9 @@ Dynamic content changes in a live region is sometimes significant, and sometimes The `aria-relevant` attribute can be used to inform assistive technologies about which kinds of changes are relevant to inform users about. It takes a list of keywords, with the following meanings: -* `additions`: Element node additions -* `text`: Text or text alternative additions -* `removals`: Text content, text alternative, or element node removals +* `additions`: Element nodes are added to the accessibility tree within the live region. +* `text`: Text content or a text alternative is added to any descendant in the accessibility tree of the live region. +* `removals`: Text content, a text alternative, or an element node within the live region is removed from the accessibility tree. * `all`: Synonym to `additions removals text` If `aria-relevant` is not specified, then the value of the closest ancestor element with an `aria-relevant` attribute is used. Specifying the `aria-relevant` attribute on an element overrides any value specified on an ancestor element. If there is no ancestor element with an `aria-relevant` attribute, the default value `additions text` is used. @@ -61,6 +61,8 @@ For example, a list of online contacts could use `aria-live="all"`: ``` When a contact comes online, it is added to the list, and users of assistive technology are informed of the addition without disrupting their current task. Similarly when a user goes offline. If a contact changes their display name, the text change would also be announced. +Note that additions and removals in the accessibility tree can happen due to changes to the DOM tree or changes to the applied CSS. For example, changing the CSS `display` property to `none` causes the element to be removed from the accessibility tree. See the Accessibility tree section for more details. + ### `aria-atomic` The `aria-atomic` attribute takes the values "true" and "false". The attribute can also be omitted. From 7e48d4dab1e703ebaac2c0be3cb393b7fa9c3b47 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Fri, 30 Aug 2019 16:24:57 +0200 Subject: [PATCH 06/14] Add an example of the output element --- live-regions.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/live-regions.md b/live-regions.md index afe7195d29..3d38e0ffac 100644 --- a/live-regions.md +++ b/live-regions.md @@ -153,6 +153,16 @@ For example, the search result summary example above could use `role="status"` i ``` +The HTML `output` element has the `status` role by default. The `output` element is defined to represent the result of a calculation performed by the application, or the result of a user action. The result of a user search is thus appropriate use of the `output` element: + +``` +
+ + + +
+``` + ### `timer` The `timer` role is a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point. From 83dd3265843aa76ad3c564674d2e099320be8e48 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 5 Dec 2019 13:25:12 +0100 Subject: [PATCH 07/14] Reorder sections and have more context in headings --- live-regions.md | 110 +++++++++++++++++++++++++++--------------------- 1 file changed, 61 insertions(+), 49 deletions(-) diff --git a/live-regions.md b/live-regions.md index 3d38e0ffac..2a25aea622 100644 --- a/live-regions.md +++ b/live-regions.md @@ -8,7 +8,7 @@ Examples of live regions are a chat log and an error message. However, different ARIA has the following attributes mark up live regions. -### `aria-live` +### Enable Live Regions with `aria-live` The `aria-live` attribute indicates that an element is a live region. Some roles implicitly set `aria-live`; this is discussed in a later section. @@ -36,7 +36,28 @@ async function updateSearch(event) { ``` -### `aria-relevant` +### Indicate What Content to Announce with `aria-atomic` + +The `aria-atomic` attribute takes the values "true" and "false". The attribute can also be omitted. + +When this attribute is set to `true`, assistive technologies will render the element as a whole, and not just parts that have been changed. + +When this attribute is set to `false`, assistive technologies will only render the changes (as per `aria-relevant`) to the user. + +When this attribute is omitted, the user agent will use the closest ancestor that has `aria-atomic` set to `true` or `false`, or if there is no such ancestor, `false`. + +For example, consider a clock that can be set to notify the user of the current time at a regular interval. Without `aria-atomic`, the assistive technology might only notify the changed components, rather than the full time. + +``` +
+ The time is + 16:34:05 +
+``` + +### Indicate Which Content Changes are Relevant with `aria-relevant` + +TODO update this to recommend only the default value. Dynamic content changes in a live region is sometimes significant, and sometimes not, depending on the kind of live region. For example, a disappearing old message in a chat log is not significant, and users do not need to be informed of the removal. However, for a list of online contacts, a disappearing contact is significant (it indicates that the contact is no longer online). @@ -63,55 +84,15 @@ When a contact comes online, it is added to the list, and users of assistive tec Note that additions and removals in the accessibility tree can happen due to changes to the DOM tree or changes to the applied CSS. For example, changing the CSS `display` property to `none` causes the element to be removed from the accessibility tree. See the Accessibility tree section for more details. -### `aria-atomic` - -The `aria-atomic` attribute takes the values "true" and "false". The attribute can also be omitted. +### Triggering Live Regions -When this attribute is set to `true`, assistive technologies will render the element as a whole, and not just parts that have been changed. - -When this attribute is set to `false`, assistive technologies will only render the changes (as per `aria-relevant`) to the user. - -When this attribute is omitted, the user agent will use the closest ancestor that has `aria-atomic` set to `true` or `false`, or if there is no such ancestor, `false`. - -For example, consider a clock that can be set to notify the user of the current time at a regular interval. Without `aria-atomic`, the assistive technology might only notify the changed components, rather than the full time. - -``` -
- The time is - 16:34:05 -
-``` - -### `aria-busy` - -Sometimes, it takes some time for a script to update the content of a live region. For example, it could be waiting on a network response. In order to avoid rendering half-baked content to users of assistive technology, the `aria-busy` attribute can be set to `true` while the content is being updated, and then to `false` when it is done. - -Consider again the search form from the earlier example. When the user starts typing a new search into the search field, the script would update the search results live region, and maybe update multiple times as new search results appear, but it would be a better experience for users of assistive technology to only be notified when the new search is complete. - -``` -
- - -
-
- -``` +TODO ## Special Case Live Regions The roles listed below implicitly set the `aria-live` attribute to indicate that it is a live region. When using these roles, the `aria-live` attribute can be omitted, or it can be specified to change the value from the default. -### `alert` +### Live Region Role `alert` The `alert` role indicates important, usually time-sensitive, information. Use this role when focus is not moved to the message, and the user is not expected to close the message. For an alert dialog that can be closed, the the `alertdialog` role instead. @@ -119,7 +100,7 @@ The default value for `aria-live` is `assertive`. The default value for `aria-at See the [Alert design pattern](#alert) and the related [Alert Example](https://w3c.github.io/aria-practices/examples/alert/alert.html). -### `log` +### Live Region Role `log` The `log` role indicates that new information is added in meaningful order and old information might disappear. @@ -135,7 +116,7 @@ For example, a chat log would be an appropriate use case for the `log` role. ``` -### `status` +### Live Region Role `status` The `status` role indicates that content is advisory information for the user but is not important enough to justify an `alert`, often but not necessarily presented as a status bar. @@ -163,7 +144,9 @@ The HTML `output` element has the `status` role by default. The `output` element ``` -### `timer` +### Live Region Role `timer` + +TODO update to discourage use. The `timer` role is a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point. @@ -178,7 +161,9 @@ For example, a countdown to New Year could use `role="timer"`.

2 minutes, 51 seconds

``` -### `marquee` +### Live Region Role `marquee` + +TODO update to discourage use. The `marquee` role indicates non-essential information that changes frequently. @@ -193,3 +178,30 @@ For example, a stock ticker that is crawling across the screen could use `role="

Banana $12.30 +0.09

``` + +# Defer Exposing Content Updates using `aria-busy` + +Sometimes, it takes some time for a script to update the content of a live region or a widget. For example, it could be waiting on a network response. In order to avoid rendering half-baked content to users of assistive technology, the `aria-busy` attribute can be set to `true` while the content is being updated, and then to `false` when it is done. + +Consider the search form from the earlier example in the [Live Resions](#live-regions) section. When the user starts typing a new search into the search field, the script would update the search results live region, and maybe update multiple times as new search results appear, but it would be a better experience for users of assistive technology to only be notified when the new search is complete. + +``` +
+ + +
+
+ +``` + +TODO link to Feed design pattern From 4c1b1aa79c0ff039ae8a227cc3f99e94e9a89ff5 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 5 Dec 2019 14:32:43 +0100 Subject: [PATCH 08/14] Additions to aria-busy --- live-regions.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/live-regions.md b/live-regions.md index 2a25aea622..94c78e71bf 100644 --- a/live-regions.md +++ b/live-regions.md @@ -183,6 +183,10 @@ For example, a stock ticker that is crawling across the screen could use `role=" Sometimes, it takes some time for a script to update the content of a live region or a widget. For example, it could be waiting on a network response. In order to avoid rendering half-baked content to users of assistive technology, the `aria-busy` attribute can be set to `true` while the content is being updated, and then to `false` when it is done. +The ARIA specification allows, but does not require, assistive technologies to wait until `aria-busy` is changed to `false` before exposing content changes to the user. So assistive technologies are allowed to ignore the `aria-busy` attribute. + +For assistive technologies that honor the `aria-busy` attribute, one possible implementation strategy is to not announce any content for elements when `aria-busy` is set to `true`. Therefore, it is important that the attribute is changed back to `false` when the content ought to be available to the user. For example, when the update is complete, but also when there is an error, or if the update is aborted. Otherwise, content could be left inaccessible to assistive technology users. + Consider the search form from the earlier example in the [Live Resions](#live-regions) section. When the user starts typing a new search into the search field, the script would update the search results live region, and maybe update multiple times as new search results appear, but it would be a better experience for users of assistive technology to only be notified when the new search is complete. ``` @@ -196,9 +200,13 @@ async function updateSearch(event) { const statusElement = document.getElementById('search-result-status'); statusElement.ariaBusy = 'true'; statusElement.textContent = 'Searching...'; - const results = await getSearchResults(event.target.value); + try { + const results = await getSearchResults(event.target.value); + statusElement.textContent = `${results.length} result(s) found.`; + } catch (ex) { + statusElement.textContent = "There was an error when searching. Please try again."; + } statusElement.ariaBusy = 'false'; - statusElement.textContent = `${results.length} result(s) found.`; showResults(results); } From e788ca2475c972467f89619dcb841211896bd861 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 5 Dec 2019 14:35:11 +0100 Subject: [PATCH 09/14] Tweak to the code in aria-busy example --- live-regions.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/live-regions.md b/live-regions.md index 94c78e71bf..fd23dd6e63 100644 --- a/live-regions.md +++ b/live-regions.md @@ -200,15 +200,16 @@ async function updateSearch(event) { const statusElement = document.getElementById('search-result-status'); statusElement.ariaBusy = 'true'; statusElement.textContent = 'Searching...'; + let results = null; try { - const results = await getSearchResults(event.target.value); + results = await getSearchResults(event.target.value); statusElement.textContent = `${results.length} result(s) found.`; } catch (ex) { statusElement.textContent = "There was an error when searching. Please try again."; } statusElement.ariaBusy = 'false'; showResults(results); -} + } ``` From 5b6adc4d1f3374a2433ccda46efa38f19199c9fc Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 5 Dec 2019 14:56:22 +0100 Subject: [PATCH 10/14] Update live-regions.md --- live-regions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/live-regions.md b/live-regions.md index fd23dd6e63..a22360a995 100644 --- a/live-regions.md +++ b/live-regions.md @@ -213,4 +213,4 @@ async function updateSearch(event) { ``` -TODO link to Feed design pattern +The [Feed Design Pattern](#feed) uses `aria-busy` in its example. A feed is a section of a page that automatically loads new sections of content as the user scrolls. While the feed is loading new content, `aria-busy` is set to `true` on the feed. From d769a55b8e466bb6cbe8b5944841399305e88c46 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 5 Dec 2019 15:27:07 +0100 Subject: [PATCH 11/14] Summarize the states and properties in a table; summarize the roles in a list --- live-regions.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/live-regions.md b/live-regions.md index a22360a995..14e6b16c49 100644 --- a/live-regions.md +++ b/live-regions.md @@ -8,6 +8,13 @@ Examples of live regions are a chat log and an error message. However, different ARIA has the following attributes mark up live regions. +State/property | Description +----------------|------------ +`aria-live` | Enables a live region. +`aria-atomic` | Indicates what content to announce. +`aria-relevant` | Indicates which content changes are relevant. +`aria-busy` | Defers content updates. Not specific to live regions. See the [next section](#aria-busy). + ### Enable Live Regions with `aria-live` The `aria-live` attribute indicates that an element is a live region. Some roles implicitly set `aria-live`; this is discussed in a later section. @@ -92,6 +99,12 @@ TODO The roles listed below implicitly set the `aria-live` attribute to indicate that it is a live region. When using these roles, the `aria-live` attribute can be omitted, or it can be specified to change the value from the default. +* `alert` +* `log` +* `status` +* `timer` +* `marquee` + ### Live Region Role `alert` The `alert` role indicates important, usually time-sensitive, information. Use this role when focus is not moved to the message, and the user is not expected to close the message. For an alert dialog that can be closed, the the `alertdialog` role instead. From 4be527c3b934f5a4bacb0217799ee0379ab79602 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 5 Dec 2019 15:37:54 +0100 Subject: [PATCH 12/14] Discourage use of timer and marquee --- live-regions.md | 35 +++++------------------------------ 1 file changed, 5 insertions(+), 30 deletions(-) diff --git a/live-regions.md b/live-regions.md index 14e6b16c49..b406e631f7 100644 --- a/live-regions.md +++ b/live-regions.md @@ -157,40 +157,15 @@ The HTML `output` element has the `status` role by default. The `output` element ``` -### Live Region Role `timer` +### Live Region Role `timer` and `marquee` -TODO update to discourage use. +Usage of the `timer` and `marquee` roles is discouraged. -The `timer` role is a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point. +The `timer` role is a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point. The `timer` role is a subclass of the `status` role. The default value of `aria-live` value of `off`. -The `timer` role is a subclass of the `status` role. The default value of `aria-live` value of `off`. +The `marquee` role indicates non-essential information that changes frequently. The default value of `aria-live` value of `off`. -Update the text content of the element to the current time measurement when it changes. - -For example, a countdown to New Year could use `role="timer"`. - -``` -

New Year Countdown

-

2 minutes, 51 seconds

-``` - -### Live Region Role `marquee` - -TODO update to discourage use. - -The `marquee` role indicates non-essential information that changes frequently. - -The default value of `aria-live` value of `off`. - -For example, a stock ticker that is crawling across the screen could use `role="marquee"`. - -``` -
-

Goosoft $8.24 +0.36

-

Microle $35.60 −0.78

-

Banana $12.30 +0.09

-
-``` +Note: [Issue 1104 for the ARIA specification] proposes deprecating these roles. # Defer Exposing Content Updates using `aria-busy` From 6678012a2679b47ba441e8f37620bb0d97f84c07 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Fri, 6 Dec 2019 16:18:33 +0100 Subject: [PATCH 13/14] Update aria-relevant to discourage "removals"; move a paragraph to Triggering Live Regions --- live-regions.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/live-regions.md b/live-regions.md index b406e631f7..1e700a9d46 100644 --- a/live-regions.md +++ b/live-regions.md @@ -64,10 +64,6 @@ For example, consider a clock that can be set to notify the user of the current ### Indicate Which Content Changes are Relevant with `aria-relevant` -TODO update this to recommend only the default value. - -Dynamic content changes in a live region is sometimes significant, and sometimes not, depending on the kind of live region. For example, a disappearing old message in a chat log is not significant, and users do not need to be informed of the removal. However, for a list of online contacts, a disappearing contact is significant (it indicates that the contact is no longer online). - The `aria-relevant` attribute can be used to inform assistive technologies about which kinds of changes are relevant to inform users about. It takes a list of keywords, with the following meanings: * `additions`: Element nodes are added to the accessibility tree within the live region. @@ -77,23 +73,33 @@ The `aria-relevant` attribute can be used to inform assistive technologies about If `aria-relevant` is not specified, then the value of the closest ancestor element with an `aria-relevant` attribute is used. Specifying the `aria-relevant` attribute on an element overrides any value specified on an ancestor element. If there is no ancestor element with an `aria-relevant` attribute, the default value `additions text` is used. -For example, a list of online contacts could use `aria-live="all"`: +For example, a disappearing old message in a chat log is not significant, and users do not need to be informed of the removal. +However, for a list of online contacts, a disappearing contact is significant (it indicates that the contact is no longer online). +Instead of announcing the removal of something, it is often better to add new content that tells the user what happened. +For example, "Alice is now offline" is clearer than "Alice" or "Removed, Alice". +Therefore, avoid using `removals` or `all`. + +For example, a list of online contacts: ``` -
+

Contacts

``` -When a contact comes online, it is added to the list, and users of assistive technology are informed of the addition without disrupting their current task. Similarly when a user goes offline. If a contact changes their display name, the text change would also be announced. -Note that additions and removals in the accessibility tree can happen due to changes to the DOM tree or changes to the applied CSS. For example, changing the CSS `display` property to `none` causes the element to be removed from the accessibility tree. See the Accessibility tree section for more details. +When a contact comes online, it is added to the list, and users of assistive technology are informed of the addition without disrupting their current task. To communicate what happened, the text is "Alice is now online", rather than only "Alice". + +Similarly when a user goes offline, the text could be changed to "Alice is now offline", and then be hidden from the list after a timeout. + +If a contact changes their display name, the text change would also be announced: "Alice has changed their name to 4liz". +After a timeout, the text "Alice has changed their name to " could be removed, without causing a new announcement. ### Triggering Live Regions -TODO +Additions and removals in the accessibility tree can happen due to changes to the DOM tree or changes to the applied CSS. For example, changing the CSS `display` property to `none` causes the element to be removed from the accessibility tree. See the Accessibility tree section for more details. ## Special Case Live Regions From 27b2c17e3c5105ce334e367a0fba3bc253546c81 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Fri, 6 Dec 2019 18:12:21 +0100 Subject: [PATCH 14/14] Convert to HTML --- aria-practices.html | 386 +++++++++++++++++++++++++++++++++++++++++++- live-regions.md | 210 ------------------------ 2 files changed, 385 insertions(+), 211 deletions(-) delete mode 100644 live-regions.md diff --git a/aria-practices.html b/aria-practices.html index 94add28540..cf46b5cde9 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -1024,7 +1024,7 @@

WAI-ARIA Roles, States, and Properties

  • The element that serves as an input and displays the combobox value has role combobox.
  • The combobox element has aria-controls set to a value that refers to the element that serves as the popup. - Note that aria-controls only needs to be set when the popup is visible. However, it is valid to reference an element that is not visible. + Note that aria-controls only needs to be set when the popup is visible. However, it is valid to reference an element that is not visible.
  • The popup is an element that has role listbox, tree, grid, or dialog.
  • @@ -3734,6 +3734,390 @@
    Examples
    +
    +

    Live Regions

    + +

    + Live regions are perceivable regions of a web page that are typically updated as a result of an external event when user focus might be elsewhere. + These regions are not always updated as a result of a user interaction. + By marking such elements as live regions, users of assistive technology can be informed of the updated content automatically. +

    + +

    + Examples of live regions are a chat log and an error message. + However, different kinds of live regions have different expected behavior; + users might expect an error message to disrupt what they are doing, since the error is important, + but want to wait with reading new chat messages until they are done typing their own message. +

    + +
    +

    Live Region States and Properties

    + +

    + ARIA has the following attributes mark up live regions. +

    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    State/propertyDescription
    aria-liveEnables a live region.
    aria-atomicIndicates what content to announce.
    aria-relevantIndicates which content changes are relevant.
    aria-busyDefers content updates. Not specific to live regions. See the next section.
    + +
    +

    Enable Live Regions with aria-live

    + +

    + The aria-live attribute indicates that an element is a live region. + Some roles implicitly set aria-live; this is discussed in a later section. +

    + +
      +
    • assertive: assistive technologies can interrupt the user to provide this information, + but will not move the current focus, so the user's work flow is not interrupted.
      • + +
    • polite: assistive technologies will provide this information after the user is done with their current task.
      • + +
    • off: assistive technologies will not provide this information unless this region has focus.
      • +
    + +

    + With the exception of a few roles, the default value of aria-live is off. +

    + +

    + For example, when the user types into a search field, the page could update the page with search results as the user is typing. + To inform users of assistive technology that this has happened, a polite live region can be used. + When the user is done typing, and the search is complete, the user is informed of how many results were found, + without having to move focus away from the search field. +

    + + 
    <form role="search" aria-labelledby="search">
+ <h2 id="search">Search</h2>
+ <label>Search query: <input type="search" name="q" oninput="updateSearch(event)"></label>
+ <div id="search-result-status" role="region" aria-live="polite"></div>
+</form>
+<script>
+async function updateSearch(event) {
+  const statusElement = document.getElementById('search-result-status');
+  const results = await getSearchResults(event.target.value);
+  statusElement.textContent = `${results.length} result(s) found.`;
+  showResults(results);
+}
+</script>
+
    +
    + +
    +

    Indicate What Content to Announce with aria-atomic

    + +

    + The aria-atomic attribute takes the values "true" and "false". The attribute can also be omitted. +

    + +

    + When this attribute is set to true, assistive technologies will render the element as a whole, and not just parts that have been changed. +

    + +

    + When this attribute is set to false, assistive technologies will only render the changes (as per aria-relevant) to the user. +

    + +

    + When this attribute is omitted, the user agent will use the closest ancestor that has aria-atomic set to true or false, + or if there is no such ancestor, false. +

    + +

    + For example, consider a clock that can be set to notify the user of the current time at a regular interval. + Without aria-atomic, the assistive technology might only notify the changed components, rather than the full time. +

    + + 
    <div id="clock" role="region" aria-live="polite" aria-atomic="true">
+ The time is
+ <span>16</span>:<span>34</span>:<span>05</span>
+</div>
+
    +
    + +
    +

    Indicate Which Content Changes are Relevant with aria-relevant

    + +

    + The aria-relevant attribute can be used to inform assistive technologies about which kinds of changes are relevant to inform users about. + It takes a list of keywords, with the following meanings: +

    + +
      +
    • additions: Element nodes are added to the accessibility tree within the live region.
      • +
    • text: Text content or a text alternative is added to any descendant in the accessibility tree of the live region.
      • +
    • removals: Text content, a text alternative, or an element node within the live region is removed from the accessibility tree.
      • +
    • all: Synonym to additions removals text
      • +
    + +

    + If aria-relevant is not specified, then the value of the closest ancestor element with an aria-relevant attribute is used. + Specifying the aria-relevant attribute on an element overrides any value specified on an ancestor element. + If there is no ancestor element with an aria-relevant attribute, the default value additions text is used. +

    + +

    + For example, a disappearing old message in a chat log is not significant, and users do not need to be informed of the removal. + However, for a list of online contacts, a disappearing contact is significant (it indicates that the contact is no longer online). + Instead of announcing the removal of something, it is often better to add new content that tells the user what happened. + For example, "Alice is now offline" is clearer than "Alice" or "Removed, Alice". + Therefore, avoid using removals or all. +

    + +

    + For example, a list of online contacts: +

    + + 
    <div role="region" aria-live="polite" aria-labelledby="contacts">
+ <h1 id="contacts">Contacts</h1>
+ <ul>
+  <li aria-atomic="true"><a href="/contacts/alice">Alice</a> is now online</li>
+ </ul>
+</div>
+
    + +

    + Note that this example omits the aria-relevant attribute, leaving it as the default value (additions text). +

    + +

    + When a contact comes online, it is added to the list, and users of assistive technology are informed of the addition without disrupting their current task. + To communicate what happened, the text is "Alice is now online", rather than only "Alice". +

    + +

    + Similarly when a user goes offline, the text could be changed to "Alice is now offline", + and then be hidden from the list after a timeout. +

    + +

    + If a contact changes their display name, the text change would also be announced: + "Alice has changed their name to 4liz". + After a timeout, the text "Alice has changed their name to " could be removed, without causing a new announcement. +

    +
    + +
    +

    Triggering Live Regions

    + +

    + Additions and removals in the accessibility tree can happen due to changes to the DOM tree or changes to the applied CSS. + For example, changing the CSS display property to none causes the element to be removed from the accessibility tree. + See the Accessibility tree section for more details. +

    +
    +
    + +
    +

    Special Case Live Regions

    + +

    + The roles listed below implicitly set the aria-live attribute to indicate that it is a live region. + When using these roles, the aria-live attribute can be omitted, + or it can be specified to change the value from the default. +

    + +
      +
    • alert
      • +
    • log
      • +
    • status
      • +
    • timer
      • +
    • marquee
      • +
    + +
    +

    Live Region Role alert

    + +

    + The alert role indicates important, usually time-sensitive, information. + Use this role when focus is not moved to the message, and the user is not expected to close the message. + For an alert dialog that can be closed, the the alertdialog role instead. +

    + +

    + The default value for aria-live is assertive. + The default value for aria-atomic is true. +

    + +

    + See the Alert design pattern and the related Alert Example. +

    +
    + +
    +

    Live Region Role log

    + +

    + The log role indicates that new information is added in meaningful order and old information might disappear. +

    + +

    + The default value for aria-live is polite. +

    + +

    + For example, a chat log would be an appropriate use case for the log role. +

    + + 
    <h1 id="irc-log">IRC Log</h1>
+<div role="log" aria-labelledby="irc-log">
+ <p>[10:26] &lt;Charl> ok let's test it and see if it works</p>
+ <p>[10:59] &lt;hsivonen> morning</p>
+</div>
+
    +
    + +
    +

    Live Region Role status

    + +

    + The status role indicates that content is advisory information for the user but is not important enough to justify an alert, often but not necessarily presented as a status bar. +

    + +

    + The default value for aria-live is polite. + The default value for aria-atomic is true. +

    + +

    + Do not move focus to the element with script when the content is changed. +

    + +

    + For example, the search result summary example above could use role="status" instead of role="region": +

    + + 
    <form role="search" aria-labelledby="search">
+ <h2 id="search">Search</h2>
+ <label>Search query: <input type="search" name="q" oninput="updateSearch(event)"></label>
+ <div id="search-result-status" role="status"></div>
+</form>
+
    + +

    + The HTML output element has the status role by default. + The output element is defined to represent the result of a calculation performed by the application, or the result of a user action. + The result of a user search is thus appropriate use of the output element: +

    + + 
    <form role="search" aria-labelledby="search">
+ <h2 id="search">Search</h2>
+ <label>Search query: <input type="search" name="q" oninput="updateSearch(event)"></label>
+ <output id="search-result-status"></output>
+</form>
+
    +
    + +
    +

    Live Region Role timer and marquee

    + +

    + Usage of the timer and marquee roles is discouraged. +

    + +

    + The timer role is a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point. + The timer role is a subclass of the status role. + The default value of aria-live value of off. +

    + +

    + The marquee role indicates non-essential information that changes frequently. + The default value of aria-live value of off. +

    + +

    + Issue 1104 for the ARIA specification proposes deprecating these roles. +

    +
    +
    +
    + +
    +

    Defer Exposing Content Updates using aria-busy

    + +

    + Sometimes, it takes some time for a script to update the content of a live region or a widget. + For example, it could be waiting on a network response. + In order to avoid rendering half-baked content to users of assistive technology, + the aria-busy attribute can be set to true while the content is being updated, + and then to false when it is done. +

    + +

    + The ARIA specification allows, but does not require, assistive technologies to wait until aria-busy is changed to false before exposing content changes to the user. + So assistive technologies are allowed to ignore the aria-busy attribute. +

    + +

    + For assistive technologies that honor the aria-busy attribute, one possible implementation strategy is to not announce any content for elements when aria-busy is set to true. + Therefore, it is important that the attribute is changed back to false when the content ought to be available to the user. + For example, when the update is complete, but also when there is an error, or if the update is aborted. + Otherwise, content could be left inaccessible to assistive technology users. +

    + +

    + Consider the search form from the earlier example in the Live Resions section. + When the user starts typing a new search into the search field, the script would update the search results live region, + and maybe update multiple times as new search results appear, + but it would be a better experience for users of assistive technology to only be notified when the new search is complete. +

    + + 
    <form role="search" aria-labelledby="search">
+ <h2 id="search">Search</h2>
+ <label>Search query: <input type="search" name="q" oninput="updateSearch(event)"></label>
+ <div id="search-result-status" role="region" aria-live="polite"></div>
+</form>
+<script>
+async function updateSearch(event) {
+  const statusElement = document.getElementById('search-result-status');
+  statusElement.ariaBusy = 'true';
+  statusElement.textContent = 'Searching...';
+  let results = null;
+  try {
+    results = await getSearchResults(event.target.value);
+    statusElement.textContent = `${results.length} result(s) found.`;
+  } catch (ex) {
+    statusElement.textContent = "There was an error when searching. Please try again.";
+  }
+  statusElement.ariaBusy = 'false';
+  showResults(results);
+  }
+</script>
+
    + +

    + The Feed Design Pattern uses aria-busy in its example. + A feed is a section of a page that automatically loads new sections of content as the user scrolls. + While the feed is loading new content, aria-busy is set to true on the feed. +

    +
    +

    Providing Accessible Names and Descriptions

    diff --git a/live-regions.md b/live-regions.md deleted file mode 100644 index 1e700a9d46..0000000000 --- a/live-regions.md +++ /dev/null @@ -1,210 +0,0 @@ -# Live Regions - -Live regions are perceivable regions of a web page that are typically updated as a result of an external event when user focus might be elsewhere. These regions are not always updated as a result of a user interaction. By marking such elements as live regions, users of assistive technology can be informed of the updated content automatically. - -Examples of live regions are a chat log and an error message. However, different kinds of live regions have different expected behavior; users might expect an error message to disrupt what they are doing, since the error is important, but want to wait with reading new chat messages until they are done typing their own message. - -## Live Region States and Properties - -ARIA has the following attributes mark up live regions. - -State/property | Description -----------------|------------ -`aria-live` | Enables a live region. -`aria-atomic` | Indicates what content to announce. -`aria-relevant` | Indicates which content changes are relevant. -`aria-busy` | Defers content updates. Not specific to live regions. See the [next section](#aria-busy). - -### Enable Live Regions with `aria-live` - -The `aria-live` attribute indicates that an element is a live region. Some roles implicitly set `aria-live`; this is discussed in a later section. - -* `assertive`: assistive technologies can interrupt the user to provide this information, but will not move the current focus, so the user's work flow is not interrupted. -* `polite`: assistive technologies will provide this information after the user is done with their current task. -* `off`: assistive technologies will not provide this information unless this region has focus. - -With the exception of a few roles, the default value of `aria-live` is `off`. - -For example, when the user types into a search field, the page could update the page with search results as the user is typing. To inform users of assistive technology that this has happened, a polite live region can be used. When the user is done typing, and the search is complete, the user is informed of how many results were found, without having to move focus away from the search field. - -``` -

    - - -
    -
    - -``` - -### Indicate What Content to Announce with `aria-atomic` - -The `aria-atomic` attribute takes the values "true" and "false". The attribute can also be omitted. - -When this attribute is set to `true`, assistive technologies will render the element as a whole, and not just parts that have been changed. - -When this attribute is set to `false`, assistive technologies will only render the changes (as per `aria-relevant`) to the user. - -When this attribute is omitted, the user agent will use the closest ancestor that has `aria-atomic` set to `true` or `false`, or if there is no such ancestor, `false`. - -For example, consider a clock that can be set to notify the user of the current time at a regular interval. Without `aria-atomic`, the assistive technology might only notify the changed components, rather than the full time. - -``` -
    - The time is - 16:34:05 -
    -``` - -### Indicate Which Content Changes are Relevant with `aria-relevant` - -The `aria-relevant` attribute can be used to inform assistive technologies about which kinds of changes are relevant to inform users about. It takes a list of keywords, with the following meanings: - -* `additions`: Element nodes are added to the accessibility tree within the live region. -* `text`: Text content or a text alternative is added to any descendant in the accessibility tree of the live region. -* `removals`: Text content, a text alternative, or an element node within the live region is removed from the accessibility tree. -* `all`: Synonym to `additions removals text` - -If `aria-relevant` is not specified, then the value of the closest ancestor element with an `aria-relevant` attribute is used. Specifying the `aria-relevant` attribute on an element overrides any value specified on an ancestor element. If there is no ancestor element with an `aria-relevant` attribute, the default value `additions text` is used. - -For example, a disappearing old message in a chat log is not significant, and users do not need to be informed of the removal. -However, for a list of online contacts, a disappearing contact is significant (it indicates that the contact is no longer online). -Instead of announcing the removal of something, it is often better to add new content that tells the user what happened. -For example, "Alice is now offline" is clearer than "Alice" or "Removed, Alice". -Therefore, avoid using `removals` or `all`. - -For example, a list of online contacts: - -``` -
    -

    Contacts

    -
      -
    • Alice is now online
      • -
    -
    -``` - -When a contact comes online, it is added to the list, and users of assistive technology are informed of the addition without disrupting their current task. To communicate what happened, the text is "Alice is now online", rather than only "Alice". - -Similarly when a user goes offline, the text could be changed to "Alice is now offline", and then be hidden from the list after a timeout. - -If a contact changes their display name, the text change would also be announced: "Alice has changed their name to 4liz". -After a timeout, the text "Alice has changed their name to " could be removed, without causing a new announcement. - -### Triggering Live Regions - -Additions and removals in the accessibility tree can happen due to changes to the DOM tree or changes to the applied CSS. For example, changing the CSS `display` property to `none` causes the element to be removed from the accessibility tree. See the Accessibility tree section for more details. - -## Special Case Live Regions - -The roles listed below implicitly set the `aria-live` attribute to indicate that it is a live region. When using these roles, the `aria-live` attribute can be omitted, or it can be specified to change the value from the default. - -* `alert` -* `log` -* `status` -* `timer` -* `marquee` - -### Live Region Role `alert` - -The `alert` role indicates important, usually time-sensitive, information. Use this role when focus is not moved to the message, and the user is not expected to close the message. For an alert dialog that can be closed, the the `alertdialog` role instead. - -The default value for `aria-live` is `assertive`. The default value for `aria-atomic` is `true`. - -See the [Alert design pattern](#alert) and the related [Alert Example](https://w3c.github.io/aria-practices/examples/alert/alert.html). - -### Live Region Role `log` - -The `log` role indicates that new information is added in meaningful order and old information might disappear. - -The default value for `aria-live` is `polite`. - -For example, a chat log would be an appropriate use case for the `log` role. - -``` -

    IRC Log

    -
    -

    [10:26] <Charl> ok let's test it and see if it works

    -

    [10:59] <hsivonen> morning

    -
    -``` - -### Live Region Role `status` - -The `status` role indicates that content is advisory information for the user but is not important enough to justify an `alert`, often but not necessarily presented as a status bar. - -The default value for `aria-live` is `polite`. The default value for `aria-atomic` is `true`. - -Do not move focus to the element with script when the content is changed. - -For example, the search result summary example above could use `role="status"` instead of `role="region"`: - -``` -
    - - -
    -
    -``` - -The HTML `output` element has the `status` role by default. The `output` element is defined to represent the result of a calculation performed by the application, or the result of a user action. The result of a user search is thus appropriate use of the `output` element: - -``` -
    - - - -
    -``` - -### Live Region Role `timer` and `marquee` - -Usage of the `timer` and `marquee` roles is discouraged. - -The `timer` role is a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point. The `timer` role is a subclass of the `status` role. The default value of `aria-live` value of `off`. - -The `marquee` role indicates non-essential information that changes frequently. The default value of `aria-live` value of `off`. - -Note: [Issue 1104 for the ARIA specification] proposes deprecating these roles. - -# Defer Exposing Content Updates using `aria-busy` - -Sometimes, it takes some time for a script to update the content of a live region or a widget. For example, it could be waiting on a network response. In order to avoid rendering half-baked content to users of assistive technology, the `aria-busy` attribute can be set to `true` while the content is being updated, and then to `false` when it is done. - -The ARIA specification allows, but does not require, assistive technologies to wait until `aria-busy` is changed to `false` before exposing content changes to the user. So assistive technologies are allowed to ignore the `aria-busy` attribute. - -For assistive technologies that honor the `aria-busy` attribute, one possible implementation strategy is to not announce any content for elements when `aria-busy` is set to `true`. Therefore, it is important that the attribute is changed back to `false` when the content ought to be available to the user. For example, when the update is complete, but also when there is an error, or if the update is aborted. Otherwise, content could be left inaccessible to assistive technology users. - -Consider the search form from the earlier example in the [Live Resions](#live-regions) section. When the user starts typing a new search into the search field, the script would update the search results live region, and maybe update multiple times as new search results appear, but it would be a better experience for users of assistive technology to only be notified when the new search is complete. - -``` -
    - - -
    -
    - -``` - -The [Feed Design Pattern](#feed) uses `aria-busy` in its example. A feed is a section of a page that automatically loads new sections of content as the user scrolls. While the feed is loading new content, `aria-busy` is set to `true` on the feed.