Repository navigation
Tell screen readers when the content changes (Web HIG tip #18) #36
frozonfreak
started this conversation in
General
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Someone filters orders on example.com/orders. The list updates in place: three shipped rows appear, and a heading now says "3 shipped orders." A screen reader user is still on the Status control and hears nothing, so they don't know the page changed. The results are visible. They were never announced.
Web HIG tip #18 (Quick #78): Dynamic content updates must be announced to screen readers (
aria-liveor focus management).Why it matters
An in-page update does not load a new document, so the screen reader does not announce a new page. Without a live-region update or a focus move:
Quick #78 is Quick-only guidance (no rule ID of its own). The HIG does not add a longer normative technique for this item. §8.3 notes that assistive-technology announcements stay manual: a passing automated check is not evidence that a screen reader spoke.
Before and after
This in-page filter redraws the list and leaves the announcement to chance. JavaScript stops the navigation, so this is a same-document update, not a new page:
Keep a live region in the document before the update, then change its text when the results change. This is a same-document illustration, not a complete orders app. It does not cover a full navigation: a new document is usually announced as a new page.
role="status"is a polite live region (it also impliesaria-atomic="true", so the whole message is read). Updating its text is not a promise that a given screen reader will speak, or when it will speak. If the update is a new view rather than a short status, moving focus toresults-headingcan be the clearer path — that is the "or focus management" half of Quick #78. A heading is not focusable by default: addtabindex="-1"so it can receive focus without joining the tab order. Do not combine a verbose live message and a focus move for the same change without checking that the pair is not noisy. This snippet does not implement fetching, errors, empty results, or a framework lifecycle. Setting the same status text again may not be announced; some implementations clear the region, then set the new text.Do this instead
role="status"is a usual starting pointaria-liveon a large, frequently changing block such as the whole results list; announce a short status insteadtabindex="-1"so it can take focus without joining the tab order. A heading's name usually comes from its text; a generic container needs an accessible nameQuick check for your app
On a test copy of example.com/orders, run an in-page filter or save with a screen reader your audience uses, and with the keyboard alone. Confirm that the change is announced, or that focus moved to the new content, and that typing a query does not flood announcements. Suitable automated checks can flag a missing live region or a missing focus target; they cannot confirm that assistive technology spoke. Pair them with a manual check on the browsers and screen readers you support. A green suite is evidence for what it actually exercised, not proof that every update is announced.
The Web HIG is an open set of guidelines for how the web should behave, not a component library. Design systems define how it looks. The Web HIG defines how it behaves.
All reactions