nextjs - ✅(Solved) Fix Accessibility (a11y): next-route-announcer only announces title changes, H1/path fallbacks never used [1 pull requests, 3 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vercel/next.js#86660Fetched 2026-04-08 02:09:58
View on GitHub
Comments
3
Participants
3
Timeline
11
Reactions
0
Author
Timeline (top)
commented ×3referenced ×2subscribed ×2cross-referenced ×1

Root Cause

Sites should provide a unique title per page, according to WCAG SC 2.4.2. However, there could plausibly be minor state variations in the path. (IE: /product?sort=price vs /product?sort=rating OR /order/dinein vs /order/carryout). In this case, when the document title does not change, no announcement will be made by the next-route-announcer. This is not accessible; because a navigation has still occurred, UI may have changed slightly, focus may have shifted, and the user needs to be made aware of that.

Fix Action

Fixed

PR fix notes

PR #4: Implement cascading logic for AppRouterAnnouncer

Description (problem / solution / changelog)

What?

  • Added cascading fallback logic to the AppRouterAnnouncer to handle cases prioritizing page title, followed by H1 tags, and then the path.
  • Ensures smooth announcements of route changes depending on the available context data.
  • Comprehensive unit tests included for various cascade scenarios.

Why?

  • To improve the accessibility and context-awareness of route announcement behavior.
  • Provides a fallback mechanism for cases where certain context data (like title or H1) might be missing.

How?

  • Implemented logic in AppRouterAnnouncer that prioritizes title > H1 > path for route change announcements.
  • Added unit tests to confirm logic consistency across all cascade scenarios.

Closes #86660 Fixes #86660 -->

Changed files

  • packages/next/src/client/components/app-router-announcer.tsx (modified, +40/-15)
  • test/unit/app-router-announcer.test.tsx (added, +319/-0)

Code Example

Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 11 Pro
  Available memory (MB): 65450
  Available CPU cores: 24
Binaries:
  Node: 25.2.1
  npm: 11.6.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 16.1.0-canary.4 // Latest available version is detected (16.1.0-canary.4).
  eslint-config-next: N/A
  react: 19.2.0
  react-dom: 19.2.0
  typescript: 5.9.3
Next.js Config:
  output: N/A
RAW_BUFFERClick to expand / collapse

Link to the code that reproduces this issue

https://github.com/Unit2795/next-announcer-issue

To Reproduce

  1. Ensure you have a screen reader and node.js installed.
  2. Clone the repository.
  3. Install dependencies using npm install.
  4. Run the development server using npm run dev.
  5. Start your screen reader
  6. Open the application in a web browser, you should see the homepage with a few link buttons.
  7. Click on the "Test" link to navigate to the /test page
  8. Observe that the screen reader announces the navigation change.
  9. Click on the "Test with Subpath" link to navigate to the /test/subpath page.
  10. Observe that the screen reader does not announce the navigation change.

Current vs. Expected behavior

Current:

  1. If there is a document title, check if it changed. If it didn't change, do not announce a change.
  2. Fallback to <h1> only occurs if there is no page title at all. (IE: document.title is undefined, null, or falsy.)
  3. Since pages usually have a title, the H1 fallback path is effectively a no-op.
  4. The path is never announced.

Expected:

  1. If document title changed, announcer reads new title. If unchanged, proceed to next step:
  2. If h1 changed, announcer reads new h1. If unchanged, proceed to next step:
  3. If URL path changed, announcer reads URL path

Provide environment information

Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 11 Pro
  Available memory (MB): 65450
  Available CPU cores: 24
Binaries:
  Node: 25.2.1
  npm: 11.6.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 16.1.0-canary.4 // Latest available version is detected (16.1.0-canary.4).
  eslint-config-next: N/A
  react: 19.2.0
  react-dom: 19.2.0
  typescript: 5.9.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Linking and Navigating

Which stage(s) are affected? (Select all that apply)

next dev (local), next build (local), next start (local), Vercel (Deployed), Other (Deployed)

Additional context

The next-route-announcer accessibility live region will generally only announce route changes when the document.title changes. It will not announce the title change only when there is no title at all (document.title is undefined, null, or falsy), but most sites generally have a title. So the logic for announcing based on an h1 or path is essentially a no op.

https://github.com/vercel/next.js/blob/737ddf775b491fb123fde41cc21a6a2d7ad599b9/packages/next/src/client/components/app-router-announcer.tsx#L48-L66

Based on the documentation (Next.js - Architecture: Accessibility), I would anticipate that the behavior should be cascading like I described in my expected behavior. What's more, the documentation for the app router mentions that the final fallback is to announce the path, but no such logic to announce the path exists for the app-router-announcer.

Sites should provide a unique title per page, according to WCAG SC 2.4.2. However, there could plausibly be minor state variations in the path. (IE: /product?sort=price vs /product?sort=rating OR /order/dinein vs /order/carryout). In this case, when the document title does not change, no announcement will be made by the next-route-announcer. This is not accessible; because a navigation has still occurred, UI may have changed slightly, focus may have shifted, and the user needs to be made aware of that.

extent analysis

TL;DR

The next-route-announcer should be modified to announce route changes based on a cascading logic of document title, h1, and URL path to ensure accessibility.

Guidance

  • Review the app-router-announcer.tsx file in the Next.js repository to understand the current implementation of route announcements.
  • Consider modifying the next-route-announcer to include a fallback logic to announce the URL path when the document title and h1 do not change.
  • Check the Next.js documentation on accessibility and route announcements to ensure compliance with WCAG guidelines.
  • Test the modified next-route-announcer with different scenarios, including changes in document title, h1, and URL path, to ensure that the expected behavior is achieved.

Example

// Example of a possible modification to the app-router-announcer.tsx file
if (document.title !== previousTitle) {
  // Announce the new title
} else if (h1 !== previousH1) {
  // Announce the new h1
} else if (window.location.pathname !== previousPathname) {
  // Announce the new URL path
}

Notes

The current implementation of the next-route-announcer only announces route changes when the document title changes, which may not be sufficient for accessibility. The proposed modification aims to address this issue by including a cascading logic to announce changes in the h1 and URL path.

Recommendation

Apply a workaround by modifying the next-route-announcer to include the proposed cascading logic, as the current implementation does not meet the expected behavior for accessibility.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

nextjs - ✅(Solved) Fix Accessibility (a11y): next-route-announcer only announces title changes, H1/path fallbacks never used [1 pull requests, 3 comments, 3 participants]