[a11y] Route Announcements

[kyleboss]

Route Announcements

Summary

This PR improves the accessibility of NextJS's client-side navigation by announcing route changes to screen readers.

Context

When a user who is sighted clicks on a link, they can see the content change. It's an affirmation that what the user intended to do by clicking a link actually worked! Users navigating the page via a screen-reader will not get this feedback on NextJS sites (This is an issue on many SPA-like architectures).

nextjs-before.mov

Solution

Whenever there is a route change, the new <RouteAnnouncer /> will look for a name to give the new page and then announce it! The name is found by first looking for an h1, falling back to document.title, and lastly to pathname. <RouteAnnouncer /> is a visually hidden component placed within the <AppContainer />.

Demo

nextjs-after.mov

Inspiration

First and foremost, this PR was inspired by @marcysutton's studies and writing, What we learned from user testing of accessible client-side routing techniques with Fable Tech Labs
as well as @madalynrose's Accessible Routing PR for Gatsby.

There were also learnings gleaned from the conversations within #7681.

Related Issues & PRs

• Resolves Routing isn't screen-reader accessible? #7681
• Relates to What to do with focus after page transition? #19963

[marcysutton]

Cool PR! I's really great that you took the time and effort to put this together, as the impact of inaccessible client-side routing is quite broad with the number of NextJS sites out there.

A couple of high-level notes:

Without routing-change announcements, keyboard users currently do not get that same feedback on NextJS sites (FWIW: This is an issue on many SPA-like architectures).

The announcements are for screen readers and other assistive technologies, so keyboard users wouldn't really benefit from that detail. Moving keyboard focus is more relevant in that case.

The page will then look for an h1, falling back to a main, and lastly to document.body to bring the user's focus to. Do note that in order to give focus to these elements, a tabIndex is levied temporarily until the element is unfocused.

The research of mine that you mentioned recommended that focus should be sent to a small, keyboard-interactive element like a skip link. Sending focus to an h1 or wrapper element works for some aspects, but wasn't really the recommended solution. I also want to make sure visible focus outlines are considered, even if it takes using :focus-visible or something like what-input to keep mouse users happy. There is a lot of value in showing the user's focus point after it moves, and focus outlines are often turned off for wrapper elements (and in general).

Lastly, to the Vercel team: I wish this issue hadn't been left to the community to take on as accessibility is an important concern for all framework core teams, and you need to address it. I hope this PR will get the reviews and attention it requires to move forward.

[jhackett1]

the example videos seem to be broken - can we fix it?

[kyleboss]

Hey @jhackett1 -- Which example videos appear to be broken? The ones in the PR description seem to be working for me.

[jonasatmonday]

Hello, we are using Next 10.2.0 and as I read it, this feature should be available since Next 10.0.9. For some reason, it does not work and still focuses something in the middle of the page upon rendering the new page. We have however a <h1> element (two in fact due to a chat overlay - is this a problem or will it just use the first h1 it finds?). As a fallback, the mechanism should also be able to use our title in the HTML-head:

<title>Rückrufservice</title>

Do we need to configure anything specific to use the new <RouteAnnouncer/>?

Edit: I tested with the MacOS VoiceOver for the announcement of the new page.
Edit: I now tested it on a page that only has one h1 and there the announcement works. Google states that multiple <h1> element on a page are not a problem as long as they semantically make sense. Which is the case with a chat overlay button bringing in a <h1>. I will open a separate issue with a request to support multiple <h1>.
Last edit (I guess): I debugged the route-announcer and figured out, that multiple <h1> are not the issue as the document.querySelector('h1') will find the first element. The problem is with the path not changing and therefore the useEffect is not triggered. That's an issue in our project we need to figure out.

[gaearon]

Is reliance on innerText over textContent (where available) intentional? I'm seeing it in the style recalc traces.

Per https://gist.github.com/paulirish/5d52fb081b3570c81e3a, reading innerText invalidates layout.

---

Based on their difference seems like it's intentional but it's still nice if there was some way to opt out of the innerText use and somehow let the developer specify the text to announce directly.

[KittyGiraudel]

I didn’t do extensive tests but my understanding is that textContent could yield incorrect results if the h1 element we read the text from contains visually hidden content.

This StackOverflow answer explains it nicely with a concise example:

innerText returns the visible text contained in a node, while textContent returns the full text. For example, on the following HTML <span>Hello <span style="display: none;">World</span></span>, innerText will return 'Hello', while textContent will return 'Hello World'.

Invisible content within a node could happen for a variety of reasons: it could be added to provide additional context for assistive technologies, it could be an editing artefact from a CMS, it could be an SVG icon or a temporarily hidden anchor link to jump to the h1.

It feels like innerText is overall safer and more aligned with what is expected (visual text). I’m curious though, is the performance difference that significant?

[shuding]

Another choice is to make document.title take priority over h1.innerText/h1.textContent, which also makes sense. I don’t remember why we went with the other way though.

[KittyGiraudel]

Another choice is to make document.title take priority over h1.innerText/h1.textContent, which also makes sense. I don’t remember why we went with the other way though.

I’ve been meaning to issue a pull-request for this since April and I originally didn’t have time and then I simply forgot. But yes, we definitely should, as mentioned in that issue. I’ll put this back onto my radar.

This won’t eliminate the issue outlined by Dan though, it will just make it less likely.

Edit: done. :)

[gaearon]

Amazing, thank you.