facebook / facebook/docusaurus

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

Open
#11,332 9 comments 0 reactions 0 assignees View on GitHub
bug status: needs triage
Dominant language
TypeScript
Stars
66.2k
Forks
10k
Avg merge
1d 3h
Merged PRs (30d)
52

Description

### Have you read the Contributing Guidelines on issues?

- [x] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#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](https://developer.mozilla.org/en-US/docs/Web/API/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](https://www.w3.org/TR/WCAG22/#status-messages) failure (does it fit the [definition of a status message](https://www.w3.org/TR/WCAG22/#dfn-status-messages)?).

### 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"` 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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.