Add option to turn off next-route-announcer

[WestonThayer]

Goals

1. Add configuration option to disable next-route-announcer

Non-Goals

1. Disable next-route-announcer by default (it's good that it's on out-of-the-box)

Background

next-route-announcer / https://nextjs.org/docs/accessibility#route-announcements assumes it's strategy of an assertive ARIA live region that announces the page title / h1 / pathname is desirable for all apps.

But many apps explicitly manage focus on route transitions (ex: Slack), moving it between interactive elements. Screen readers and other assistive technologies follow/announce focus, so next-route-announcer adds unnecessary noise to the UX.

Please provide a way to disable next-route-announcer.

Proposal

https://nextjs.org/docs/advanced-features/custom-app or https://nextjs.org/docs/api-reference/next.config.js/introduction seem like natural configuration seem like natural places to configure to me, but I don't feel strongly.

[jussimi]

An ugly workaround is to set the display of the route-announcer to none.

#__next-route-announcer__ {
  display: none;
}

The component remains in the document, but at least screen-readers don't read the content.

[harshtohai]

next-route-announcer{
display:none;
}

add this to global.css and done.

[lucasbasquerotto]

The next-route-announcer component is causing CSP style issues due to not having a way to define a nonce in a configuration for it, at least not that I found (it creates a component <next-route-announcer style="position: absolute"></next-route-announcer>), which means that it seems to not be production ready yet.

CSS workarounds do not solve this issue. The component must not be included in the DOM.

Is there no way to disable it? I keep receiving this error in our production build, and NextJS seems to force this component with no way to disable it.

[OoMNoO]

Temporary Workaround for next-route-announcer CSP style-src Violation

This is a temporary workaround for the CSP error caused by the next-route-announcer component's inline styles. It involves patching the Next.js source in node_modules until an official fix is provided.

Root Cause

The AppRouterAnnouncer component injects elements with inline styles (style attributes), which violates a strict Content Security Policy (CSP) that does not allow 'unsafe-inline'.

Solution 1: Complete Removal (Recommended for custom accessibility solutions)

If you manage route announcements manually, you can completely remove the announcer.

File: node_modules/next/dist/client/components/app-router.js

Action: Locate and comment out the line that renders the AppRouterAnnouncer component.

// /*#__PURE__*/ (0, _jsxruntime.jsx)(_approuterannouncer.AppRouterAnnouncer, {
//     tree: tree
// })

Clear the .next cache and rebuild your project.

rm -rf .next
npm run build

Solution 2: Remove Inline Styles & Use CSS (Recommended to preserve accessibility)

This solution preserves the accessibility features while fixing the CSP error by moving all styles to a CSS file.

Step 1: Patch the Next.js Source Files

Patch the following files to prevent the inline styles from being generated:

File 1: node_modules/next/dist/client/components/app-router-announcer.js

• Locate and comment out the lines that set container.style.cssText and announcer.style.cssText.

// container.style.cssText = 'position:absolute'; 
// announcer.style.cssText = 'position:absolute;border:0;height:1px;margin:-1px;padding:0;width:1px;clip:rect(0 0 0 0);overflow:hidden;white-space:nowrap;word-wrap:normal';

File 2: node_modules/next/dist/client/route-announcer.js

• Locate and comment out the style prop for the announcer element.

return /*#__PURE__*/_jsxruntime.jsx("next-route-announcer", {
    // style: nextjsRouteAnnouncerStyles, // <-- Comment this line
    "aria-live": "assertive",
    id: "__next-route-announcer__",
    role: "alert",
    children: /*#__PURE__*/_jsxruntime.jsx("p", {
        children: announcement
    })
});

Step 2: Add Global CSS Styles

Add the following rules to your global CSS file (e.g., app/globals.css) to apply the required visually hidden styles without inline code.

/* Replaces the inline styles for the next-route-announcer to fix CSP */
next-route-announcer {
  position: absolute !important;
}

next-route-announcer > div {
  position: absolute !important;
  width: 1px !important;
  height: 1px !important;
  padding: 0 !important;
  margin: -1px !important;
  overflow: hidden !important;
  clip: rect(0, 0, 0, 0) !important;
  white-space: nowrap !important;
  border: 0 !important;
}

next-route-announcer > p {
  position: absolute !important;
  width: 1px !important;
  height: 1px !important;
  padding: 0 !important;
  margin: -1px !important;
  overflow: hidden !important;
  clip: rect(0, 0, 0, 0) !important;
  white-space: nowrap !important;
  border: 0 !important;
}

Step 3: Clean and Rebuild

Clear the Next.js cache and rebuild your application for the changes to take effect.

rm -rf .next
npm run build

Important Notes

• This is a temporary fix. These changes will be overwritten upon reinstalling node_modules or updating the Next.js version.

• Automate the patch: For a more sustainable solution, consider using patch-package to automatically re-apply these changes after every install.

• Solution 2 is preferred as it maintains accessibility for screen reader users.

• Monitor the official issue (#83764) for a permanent fix from the Next.js team.

Hope this helps others facing the same CSP issue!

[lucasbasquerotto]

@OoMNoO The changes in the local node_modules would not reflect in the CI environment, although I could define a script to automate that.

Unfortunately such a solution is normally the cause of bugs in later versions. In a previous project of mine that used cordova, I had some hooks that did that (changing some node_modules files), and some of those changes caused silent errors when updating the code, that are normally hard to find the cause (imagine such a change causing a bug years later, you probably won't even remember that you had added this code), so I try to avoid it at all costs.

Anyway, thanks for the information! It might be useful for those that consider the risk of changing the node_modules worth it.

[1hue]

This is causing hydration issues due to:

	<next-route-announcer style="position: absolute"></next-route-announcer>

v16.0.10