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

[WestonThayer]

Have you read the Contributing Guidelines on issues?

• [x] I have read the Contributing Guidelines on issues.

Prerequisites

• [x] I'm using the latest version of Docusaurus.
• [x] I have tried the npm run clear or yarn clear command.
• [x] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• [x] I have tried creating a repro with https://new.docusaurus.io.
• [x] 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.

https://github.com/user-attachments/assets/16960c37-aaac-49b4-89b9-323071c3ffde

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.

https://github.com/user-attachments/assets/6819e9a8-7346-4ac3-b271-8a3e16a8c0d4

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?

https://github.com/facebook/docusaurus/pull/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.

[Yousuf-cse]

Hi @WestonThayer, I’d like to work on improving accessibility for the Docusaurus top navigation links, ensuring screen readers like NVDA and VoiceOver announce navigation properly. Could you please assign this issue to me for Hacktoberfest? Thank you!

[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