688611a582
# 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). https://user-images.githubusercontent.com/4213649/103017382-63b02b00-44f8-11eb-9940-fb530d2d3018.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 https://user-images.githubusercontent.com/4213649/103017401-6ad73900-44f8-11eb-8050-b3e9a7e0c3f2.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 ](https://www.gatsbyjs.com/blog/2019-07-11-user-testing-accessible-client-routing/) as well as @madalynrose's [Accessible Routing](https://github.com/gatsbyjs/gatsby/pull/19290) PR for Gatsby. There were also learnings gleaned from the conversations within #7681. ### Related Issues & PRs - Resolves #7681 - Relates to #19963
67 lines
2 KiB
TypeScript
67 lines
2 KiB
TypeScript
import React, { useEffect, useState, useRef } from 'react'
|
|
import { useRouter } from './router'
|
|
|
|
export function RouteAnnouncer() {
|
|
const { asPath } = useRouter()
|
|
const [routeAnnouncement, setRouteAnnouncement] = useState('')
|
|
|
|
// Only announce the path change, but not for the first load because screen reader will do that automatically.
|
|
const initialPathLoaded = useRef(false)
|
|
|
|
// Every time the path changes, announce the route change. The announcement will be prioritized by h1, then title
|
|
// (from metadata), and finally if those don't exist, then the pathName that is in the URL. This methodology is
|
|
// inspired by Marcy Sutton's accessible client routing user testing. More information can be found here:
|
|
// https://www.gatsbyjs.com/blog/2019-07-11-user-testing-accessible-client-routing/
|
|
useEffect(
|
|
() => {
|
|
if (!initialPathLoaded.current) {
|
|
initialPathLoaded.current = true
|
|
return
|
|
}
|
|
|
|
let newRouteAnnouncement
|
|
const pageHeader = document.querySelector('h1')
|
|
|
|
if (pageHeader) {
|
|
newRouteAnnouncement = pageHeader.innerText || pageHeader.textContent
|
|
}
|
|
if (!newRouteAnnouncement) {
|
|
if (document.title) {
|
|
newRouteAnnouncement = document.title
|
|
} else {
|
|
newRouteAnnouncement = asPath
|
|
}
|
|
}
|
|
|
|
setRouteAnnouncement(newRouteAnnouncement)
|
|
},
|
|
// TODO: switch to pathname + query object of dynamic route requirements
|
|
[asPath]
|
|
)
|
|
|
|
return (
|
|
<p
|
|
aria-live="assertive" // Make the announcement immediately.
|
|
id="__next-route-announcer__"
|
|
role="alert"
|
|
style={{
|
|
border: 0,
|
|
clip: 'rect(0 0 0 0)',
|
|
height: '1px',
|
|
margin: '-1px',
|
|
overflow: 'hidden',
|
|
padding: 0,
|
|
position: 'absolute',
|
|
width: '1px',
|
|
|
|
// https://medium.com/@jessebeach/beware-smushed-off-screen-accessible-text-5952a4c2cbfe
|
|
whiteSpace: 'nowrap',
|
|
wordWrap: 'normal',
|
|
}}
|
|
>
|
|
{routeAnnouncement}
|
|
</p>
|
|
)
|
|
}
|
|
|
|
export default RouteAnnouncer
|