Single page app (SPA) route navigations sometimes not announced by screen readers (NVDA, VoiceOver)

[WestonThayer]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

I believe Docusaurus is a single page app (SPA). When internal links are invoked, the history API is used to update the browser's URL bar. This unfortunately doesn't come with out-of-the-box accessibility support https://www.matuzo.at/blog/2023/single-page-applications-criticism/. The new Navigation API should be better but not ready for prime time yet 🤞🏻

As a result, here's NVDA invoking the "Community" link in the top nav. I'm tabbing to the link, then press Enter to invoke. NVDA announces nothing.

assistivlabs_win-nvda_2025.1.1_win-chrome_137_2025-07-16T18-34-57.333Z.mp4

macOS VoiceOver is a little inconsistent. I'm again tabbing to the link. First I'm using Enter to invoke. VoiceOver consistently announces nothing. But VO+Space is another common way to invoke links/buttons. VoiceOver sometimes announces the document title in that case, it seems inconsistent.

2025-07-16.11-39-07.mp4

FWIW there's a bit of debate as to whether this is is a WCAG 4.1.3 Status Messages failure (does it fit the definition of a status message?).

Reproducible demo

https://docusaurus.io/

Steps to reproduce

1. With NVDA (and Chrome in my testing), visit docusaurus.io
2. Tab to a link in the top navigation
3. Press Enter

Expected behavior

There's a bit of debate on this (see linked blog posts), but I'd argue that since this is basically a MPA (multi page app) navigation, the MPA UX should be mimicked. In a standard MPA nav, NVDA will announce "<document.title> document" when the page is fully loaded.

Note that slower network connections should be considered — the user needs to be aware when the page is fully rendered and ready for interaction. It'd also be nice if they were informed while loading was still taking place. I know the History API doesn't give many options for this, IIRC the Navigation API has the necessary hooks.

Actual behavior

NVDA announces nothing.

Your environment

N/A

Self-service

• I'd be willing to fix this bug myself.

[slorber]

Not much time to check this currently, but we have a very old PR here, does it fix your issue?

#8110

[WestonThayer]

Yeah the live region is one common approach. A big downside is most screen readers with a refreshable braille display connected don't send ARIA live region messages on to the braille display, so the UX isn't on par with a MPA (multi page app).

An "appy" SPA like Slack solves this by always moving focus somewhere meaningful on route transitions, which solves the braille display problem.

But the PR you linked is a step in the right direction regardless.

[WestonThayer]

Hi @Yousuf-cse I'm not a Docusaurus maintainer, but @slorber is (I don't know what Hacktoberfest is).

[Josh-Cena]

It's a time when random GitHub users spam popular OSS repos to find a chance for contributions :)

@Yousuf-cse Please read our contributing guide before even considering to start working on anything, because our guide clearly says how you should claim issues.

[slorber]

Not sure yet how helpful this could be, but I noticed Chrome 141 shipping a new Aria Notify API:

• https://developer.chrome.com/release-notes/141
• https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaNotify
• https://www.w3.org/2025/Talks/aria-notify-breakouts-2025.pdf
• https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/Accessibility/AriaNotify/explainer.md

[gonzoblasco]

Adding to this because the core question here (what WCAG criterion this maps to, and which fix approach is actually robust) shapes the implementation, and I think it's worth being precise about.

On the criterion: this is closer to 2.4.2 (Page Titled) than 4.1.3 (Status Messages), and that changes the fix.

A status message (4.1.3) is an in-page state change announced without moving focus - think "results updated" or "3 items added to cart". A route navigation that swaps the whole document is not an in-page status update; it is the SPA equivalent of a page load, and the user-visible contract is the same as a MPA: the document title changes and the SR announces it. So the honest fix is to make the SPA behave like a page load, not to inject a live region that mimics one. Treating it as 4.1.3 invites the live-region band-aid, which is exactly the approach that has the braille-display gap @WestonThayer flagged.

Why the live region is the wrong primary mechanism (agreeing with @WestonThayer):

• Live regions announce on the audio channel but, as noted, do not reliably reach refreshable braille displays. A blind braille user gets the full page content on the display but no route-change signal. That is a real regression against MPA behavior.
• A live region that announces "Navigated to /docs/foo" competes with the new page's own content announcements. If the new page also moves focus or announces a heading, you get double announcements.
• Route changes in Docusaurus are fast (often < 100ms locally), so a live region that fires and clears too quickly is frequently swallowed entirely - which may be part of why the current behavior announces nothing at all.

The robust pattern is focus management, and Docusaurus is well-positioned for it.

Move focus to a meaningful, persistent landmark on route change - conventionally an h1 or a visually-hidden "skip to content" target at the top of the newly rendered page. That is the pattern Slack and other appy SPAs use, and it solves both the announcement and the braille problem in one move, because focus navigation is the one mechanism all SRs (NVDA, JAWS, VoiceOver, TalkBack) and braille displays agree on. Docusaurus already renders a persistent page h1 on doc/blog pages, so the focus target largely exists.

There are two real costs to call out so they are not surprises:

1. Moving focus changes the Tab order on every route change, which some sighted keyboard users find surprising at first. This is standard SPA behavior (Gatsby, Next.js App Router do it), and it is generally accepted as the correct trade.
2. You must also update document.title to the page title on route change (not just the site title in SiteMetadataDefaults.tsx), so the SR can announce it when focus lands. Without the title update, focus moves but the user is not told what page they are on.

On Aria Notify: promising, and slorber is right to track it, but it is not the immediate fix. It ships in Chrome 141 and its support in NVDA/VoiceOver and on braille is not settled; relying on it today means users on older browsers or other AT get nothing. It can be the long-term path, but the focus-management pattern is the robust baseline that works now across every SRM.

So my read: implement focus-move on route change (to the page h1 or a dedicated skip target) plus per-page document.title updates, and treat Aria Notify as a future enhancement layered on top, not the primary mechanism. Happy to help verify the resulting behavior against NVDA, VoiceOver, and a refreshable braille display if there is a candidate implementation to test.

[WestonThayer]

FWIW this prompted me to check in on the Navigation API. While it's supposedly "Baseline" as of January 2026, it didn't deliver the automatic support for notifying assistive technologies of route changes to all browsers. See support table in whatwg/html#12834

Agreed that focusing something is the most solid way to make every screen reader announce something. There are downsides though. For example, jumping focus to the h1 probably skips past a bunch of content. Screen reader users could not realize that content exists (as compared to an MPA where they'd always start at the top of the doc and have to manually skip past every time).

[gonzoblasco]

Good call on the Navigation API - I checked the support table in whatwg/html#12834 and you are right that "Baseline" did not translate into automatic AT notification of route changes across browsers. That reinforces treating it as a future enhancement rather than the primary mechanism.

On the focus jump downside: agreed, and it is exactly why I would not move focus to the h1 directly. The more robust target is a dedicated "skip to content" anchor at the top of the newly rendered page, which is the pattern Gatsby and the Next.js App Router use. It solves the concern you raised in two ways:

• The user lands on a meaningful, persistent landmark that announces the page (via the updated document.title), so they know the route changed and what page they are on.
• They are not forced to skip past content manually, and they do not silently lose awareness of content that sits between the top of the document and the h1. The skip target is the content entry point, so nothing is hidden from them.

The key difference from a plain h1 jump is that the skip target is a stable, expected location - screen reader users already know the "skip to content" convention, so landing there is predictable rather than surprising. It also keeps the Tab order change minimal and consistent across every route change.

So the concrete shape I would propose for a PR:

1. On route change, move focus to a visually-hidden "skip to content" target rendered at the top of the page (or reuse the existing skip link if Docusaurus has one).
2. Update document.title to the page title on route change so the SR announces the new page when focus lands.
3. Keep Aria Notify as a layered future enhancement, not the primary mechanism.

[gonzoblasco]

PR opened: #12387

Implemented the focus-management approach discussed above. Docusaurus already moved focus to the skip-to-content container on route change, but that container had a static "Skip to main content" aria-label, so the screen reader did not announce which page the user landed on.

The PR passes the page title down from the Layout to the SkipToContent component and uses it to set the container's aria-label to the formatted page title when navigating. The container is focused on route change, so the SR announces the page title. The aria-label is restored to "Skip to main content" on the next render, so the skip link keeps working for keyboard users.

I used the Layout's title prop (formatted via useTitleFormatter) rather than reading document.title, because Helmet updates document.title asynchronously (deferred via requestAnimationFrame), so it is not reliable at the moment focus moves.