w3c
Draft guidance section for live region roles and attributes
This guidance section will cover the following roles, states, and properties:
- [ ] alert
- [ ] log
- [ ] marquee
- [ ] status
- [ ] timer
- [ ] aria-atomic
- [ ] aria-busy
- [ ] aria-live
- [ ] aria-relevant
It should also explain what kinds of updates the spec says should trigger a live region. @JAWS-test asked about the following list of possibilities and concerns in issue #1138.
- Insert into DOM
- Remove from DOM
- add role=alert to an existing node
- Change visibility (display:none, hidden, aria-hidden)
- Change the position (e.g.: left:100px)
- Change the color (e.g.: color:red)
- Change the size (e.g. width:100px)
- Change transparency (e.g. opacity:0;)
However, the output differs depending on whether these changes are made to the parent element, the element with role=alert, a direct child element, or a nested descendant element. The output also varies depending on which Javascript method is used to insert element nodes into the DOM.
When working on this issue, there is some old content that may be useful in the file aria-practices-DeletedSectionsArchive.html. The relevant section can be seen here: https://rawgit.com/w3c/aria-practices/master/aria-practices-DeletedSectionsArchive.html#docmgt
Note https://www.w3.org/Bugs/Public/show_bug.cgi?id=28611 about aria-busy when drafting this section
Would be great to also have some live region examples. Here's one for status role: https://carmacleod.github.io/playground/status-role.html
I would like to make the following proposal for live regions and ARIA roles with implicit live regions:
An output of the live region should be made:
- only with aria-live=polite or aria-live=assertive (explicit or implicit) and without aria-busy=true (implicit or explicit)
With aria-relevant=all/additions/text:
- Inserting a node into the DOM (only for aria-relevant=all/additions)
- Changing or inserting text content in an existing node (only for aria-relevant=all/text)
- Change visibility:
- from display:none to display:block/inline/inline-block etc.,
- from hidden to without hidden
- from visibility:hidden/collapse to visibility:visible
- from aria-hidden=true to aria-hidden=false
- for display:none, visibility:hidden and aria-hidden=true also if the attribute or CSS property is removed
However, it should be noted that the actual visibility of the element is relevant, i.e. if I use
<div hidden>
<div hidden role=alert>
alert
</div>
</div>
and remove the hidden at the inner div, the live region should not be output, because the outer div is still hidden. As soon as the hidden is removed from the outer div, the live region should be output.
With aria-relevant=all/removals:
-
Removal of a node from the DOM
-
Remove text content
-
Change the visibility with
- display:none
- hidden
- visibility:hidden/collapse
- aria-hidden=true The difference between new content and removed content should be noticeable (e.g. JAWS outputs "removed")
-
Changing from aria-busy=true to aria-busy=false or removing aria-busy=true (but only if one of the above changes has additionally taken place in the time of aria-busy=true)
For most of the above methods, it should work if
- the parent or an ancestor element or
- the element with the live region is changed or
- the child or a descendant element.
The first two variants (ancestor element or element itself) cannot work with aria-relevant=all/removals if the live region is removed from the DOM. In this case the live region should only work if the change of visibility (via CSS, hidden or aria-hidden) is done at the element or ancestor element. A live region that no longer exists cannot lead to any output.
For all CSS methods (display, visibility) it should work if
- a class is added or removed,
- the class definition is changed,
- the content of the style attribute is changed,
- the style attribute is added or removed.
It should not matter which JavaScript method is used to insert, change or delete DOM nodes or HTML/ARIA attributes.
An output should not be made:
- if the live region is already present in the source code when the page is loaded
- if the ARIA role (or ARIA attributes - see open questions) for live regions are added to the DOM later (i.e. assigned to an existing node)
- aria-busy=true
- aria-live=off
- use of aria-relevant or aria-atomic without aria-live=political/assertive
- when changing visibility with CSS properties other than those described above, such as
- opacity
- color
- background-color
- width
- height
- position
- left, right, top, bottom
- overflow
- clip
- when changing other CSS properties
- if the change takes place within an area in the live region that is hidden (e.g. aria-hidden=true or display:none)
- if an identical output of the same content has already occurred (e.g. aria-hidden=true and display:none is removed - these are two of the changes described above, but should only lead to one output)
Open questions
- What is the difference between aria-live=off and no aria-live? The definition in https://www.w3.org/TR/wai-aria-1.2/#aria-live says: "Indicates that updates to the region should not be presented to the user unless the user is currently focused on that region." This sounds as if the focus is not on the whole region, but only on the updates. That would be a meaningful distinction to an element without aria-live, whereby the roles marquee and timer would also have a meaningful purpose (both have aria-live=off). However, this does not seem to be further specified and does not seem to work with assistive technology (it doesn't work with JAWS at the moment: when the live region with aria-live=off gets focus, everything is output). The question is also what is meant by getting focus: Tab navigation, linear reading? As an alternative to just outputting the updates, there should also be a way to output the entire content. It would be nice to implement it in such a way that an update within aria-live=off can also be output without focusing on user requirements (e.g. via access key).
- Maybe a live region should also be output if aria-live=off is changed to aria-live=polite/assertive or if aria-live=polite/assertive is added? In itself, this should also work because ARIA attributes can be changed. However, the problem is that the ARIA roles that implicitly have aria-live cannot be added dynamically. So this could be an inconsistency in the different methods to implement a live region
- Should there be a difference between role=alert and aria-live=assertive? JAWS distinguishes strongly between both live regions, according to the specification there are none. On whatsock.com/training/ from @accdc I found: "It's important to note that, when aria-live=assertive is applied to a container without the use of role=alert, it will not tie into the alert system of the Operating System. This only occurs when role=alert is included". However, I do not know whether this only reflects the test experience or whether this is defined in the specification.
- Should the specification be based on the currently most widespread implementation by assistive technologies in order to achieve the greatest possible compatibility? If so, extensive tests with different browsers, operating systems and screen readers should be carried out.
- What should be output if, for example, form fields are inserted in the live region (nothing, only the label, label and value, or even the role)?
- What should be output if the text content in the live region does not change, but e.g. the alt attribute of a graphic, the value attribute of an inputs field, the selected attribute for option within select.
- What if the text content does not change within the live region, but only text outside the live region that serves as label via
aria-labelledbyorlabelfor an element within the live region? - Should the live region be output if the focus is not on the page with the live region but in another program, on another browser tab or in the browser menu?
- Should the role of the Live Region be output when reading with the arrow keys and updating the Live Region (https://github.com/FreedomScientific/VFO-standards-support/issues/277, https://github.com/FreedomScientific/VFO-standards-support/issues/296)?
- What is considered a changed node in aria-atomic=false? What if the changed node has the same content as the previous one? (https://github.com/FreedomScientific/VFO-standards-support/issues/290, https://github.com/FreedomScientific/VFO-standards-support/issues/298)
- Should the page language be taken into account when outputting the Live Region? Should the language change within the live region be taken into account?
- Should a live region be output if the update is in an iFrame (or other embedded element like SVG, Video) and the live region is outside (see https://github.com/FreedomScientific/VFO-standards-support/issues/111).
- Which text alternatives for non-text content should be output in live regions?
- Should CSS text be output in live regions?
- Do the ARIA attributes for Live Regions have to be on the same HTML element or can they be nested? Can they be nested several times? Does aria-live always have to be the outermost attribute or can aria-atomic also be on the outside? At least aria-atomic should be allowed to be inside aria-live. But should the following also be allowed and work?
<div aria-live=polite>
<div aria-relevant=removals>
only removals are output
<div aria-relevant=all>
all is output
</div>
</div>
</div>
I am open for any changes, as long as there is an exact specification. The current implementation of live regions is very frustrating. When customers ask me how to implement a live regions across platforms and for different browsers / screen readers (in JAWS, the output of live regions changes from version to version), I can only say: Sorry, I don't know, because of the many inconsistencies and errors.
For problems with JAWS, see e.g.
- https://github.com/FreedomScientific/VFO-standards-support/issues?q=alert
- https://github.com/FreedomScientific/VFO-standards-support/issues?q=live+region
An example of the current situation with the WCAG 4.1.3 example: https://w3c.github.io/wcag/working-examples/aria-role-status-shoppingcart/ (using JAWS 2019):
- no output in Firefox
- Output of the number in IE 11
- Output of number and item in Chrome
The following recommendations are based on testing Live Regions with JAWS 2019 and Chrome, Edge, IE 11, Firefox. For the recommendations to be published on APG, the published examples should at least also be tested with NVDA, Voiceover, Talkback, and Supernova. The recommendations are not based on the ARIA specification, but on browser-specific errors. The errors are in part due to the inadequate specification.
General recommendations
- Note that the content of the live region is output as pure, unstructured text.
- Note that the content of the live region is output only once and cannot be listened to again (https://github.com/FreedomScientific/VFO-standards-support/issues/282). Therefore use Live Regions only for important and short messages. Use a simple language within the Live Region.
- Note that the attributes aria-live=polite and aria-live=assertive are output without any relevant difference (https://github.com/FreedomScientific/VFO-standards-support/issues/284). For important messages that must be output immediately, role=alert should be used.
- Do not use the aria-busy attribute. Instead, update the content in the live region with one JS statement. (https://github.com/FreedomScientific/VFO-standards-support/issues/257)
- Do not use aria-relevant, only use the default setting of aria-relevant ("additions text") (https://github.com/FreedomScientific/VFO-standards-support/issues/279, https://github.com/FreedomScientific/VFO-standards-support/issues/283)
- Use only aria-relevant="additions text" instead of aria-relevant=removals (or aria-relevant=all). If you want the screenreader to output the removal of content, then add the appropriate information to the live region, i.e. insert a text telling that an item has been removed (https://github.com/FreedomScientific/VFO-standards-support/issues/279, https://github.com/FreedomScientific/VFO-standards-support/issues/289).
- Use the aria-atomic attribute only on the same HTML attribute as the Live Region. Do not nest aria-atomic. (https://github.com/FreedomScientific/VFO-standards-support/issues/290)
- Use only innerHTML or textContent to update the live region. Do not use nodeValue, appendChild, replaceChild, insertBefore, remove or removeChild (https://github.com/FreedomScientific/VFO-standards-support/issues/279).
- Be careful not to output multiple Live Regions at the same time or in quick succession, as they may then interrupt each other (https://github.com/FreedomScientific/VFO-standards-support/issues/285). Leave enough time between outputting two Live Regions because you don't know the output speed of the user.
- Avoid HTML elements in the live region. Use plain text only (https://github.com/FreedomScientific/VFO-standards-support/issues/283, https://github.com/FreedomScientific/VFO-standards-support/issues/294, https://github.com/FreedomScientific/VFO-standards-support/issues/295).
- Don't use language changes in the live region. The lang attribute is ignored within Live regions, regardless of its location. Note that the defined side language is also ignored. The live region is always output in the default language of the screenreader (https://github.com/FreedomScientific/VFO-standards-support/issues/8).
- If there is an update in iFrame, the live region should also be in iFrame (https://github.com/FreedomScientific/VFO-standards-support/issues/111)
- Avoid graphics within live regions, because their alternative text is not output or is output multiple times (https://github.com/FreedomScientific/VFO-standards-support/issues/299)
- Do not try to reach the output of the live region by changing the visibility (hidden, display, aria-hidden, visibility) (https://github.com/FreedomScientific/VFO-standards-support/issues/261, https://github.com/FreedomScientific/VFO-standards-support/issues/265, https://github.com/FreedomScientific/VFO-standards-support/issues/267).
- Don't try to get the output of the live region by adding roles or attributes for live regions (https://github.com/FreedomScientific/VFO-standards-support/issues/263)
- Do not try to reach the Live region output by insert node with the Live region into the DOM (https://github.com/FreedomScientific/VFO-standards-support/issues/287). The live region should already be in the DOM and only then the content of the live region should be changed so that the output can be done correctly.
- Do not rely on a Live Region being output if only the DOM and not the text content has changed (https://github.com/FreedomScientific/VFO-standards-support/issues/266, https://github.com/FreedomScientific/VFO-standards-support/issues/298).
- Do not add form elements to the Live region (https://github.com/FreedomScientific/VFO-standards-support/issues/269). Note that interactive elements in the Live region cannot be operated because the Live region does not get the focus.
- Don't rely on a label change with aria-label or aria-labelledby being output correctly within a live region (https://github.com/FreedomScientific/VFO-standards-suppo
- The live regions are not output correctly when reading with the arrow keys (https://github.com/FreedomScientific/VFO-standards-support/issues/277). If the content of the live region is to be recognizable as such, a heading should be inserted before the live region or a labelled region around the live region.
- Do not rely on the Live region label being output (https://github.com/FreedomScientific/VFO-standards-support/issues/291).
- Note that Live Regions will only output reliably if the user is on the page. In some cases, however, there will also be output if the page does not have the focus (https://github.com/FreedomScientific/VFO-standards-support/issues/293). Live regions should therefore only be updated if the user interacts with the page.
- Note that live regions are not output by Edge.
- Note that Live regions are not output by Zoomtext.
- Note that page updates output via Live Region are unlikely to be noticed by visually impaired users, e.g. when using zoom or screen magnifiers. For important messages, modal pop-ups should be used to get the focus.
Browser specific recommendations
- Don't change the CSS properties of a live region (like scale, transform, overflow, position), because it will be output without changing its content (Firefox, https://github.com/FreedomScientific/VFO-standards-support/issues/118, https://github.com/FreedomScientific/VFO-standards-support/issues/262)
- Don't rely on the content of a live region being output when it gets the focus with Tab (Chrome, https://github.com/FreedomScientific/VFO-standards-support/issues/222)
- Note that invisible content, HTML comments and HTML elements can lead to unexpected reading pauses in the live region (IE 11, Chrome, https://github.com/FreedomScientific/VFO-standards-support/issues/270).
- SVG graphics within a live region are not output (Firefox, https://github.com/FreedomScientific/VFO-standards-support/issues/272, https://github.com/FreedomScientific/VFO-standards-support/issues/303).
- The alt attribute change within a live region is not output correctly (Firefox, https://github.com/FreedomScientific/VFO-standards-support/issues/273)
- Do not use aria-atomic=false with role=alert (IE 11, https://github.com/FreedomScientific/VFO-standards-support/issues/294)
There should be a note about the allowed or recommended length of a live region (especially with aria-live=assertive). See https://github.com/FreedomScientific/standards-support/issues/785