Accessibility

[mayank99]

Describe the bug

Now that tanstack router has reached v1, I was excited to try it because accessibility was promised for 1.0. I fired up one of the examples and was very disappointed to find no route announcements or focus management.

When a screen-reader user (or even a sighted keyboard user) activates a regular link, the browser will move focus to the top of the new page and the screen-reader announces meta information about the new page.

When the same user activates a <Link> from tanstack-router, the focus stays where it is or gets lost (if the link is no longer present on the new route), and the screen-reader provides absolutely no feedback. From a blind user's perspective, it's as if nothing happened or their input was ignored.

Okay, fair enough, maybe it's opt-in or there's some helpers available. So I go through the docs, and am again disappointed to find no mention of accessibility at all. So tanstack-router users are completely on their own if they want to make their applications accessible. In absence of any guidance, it's safe to assume that many (if not most) developers are not going to do that.

Your Example Website or App

https://stackblitz.com/github/tanstack/router/tree/main/examples/react/kitchen-sink-file-based

Steps to Reproduce the Bug or Issue

1. Open the page in any common screen-reader+browser combination (such as Safari+VoiceOver or Firefox+NVDA or Chrome+Talkback Android).
2. Traverse through the page using arrow keys (might also need to hold down a modifier key; see VO instructions) or Tab.
3. Activate one of the links in the sidebar.
   • The navigation happens silently, focus stays on the link.

Expected behavior

Screen-reader users should receive some feedback when clicking a link, such as "Navigated to page [title]". Focus should also generally move to the top of the new view (with some exceptions).

Not both of these (triggering an announcement and moving focus) need to happen together; one or the other may be sufficient depending on the scenario. What matters is that there is some feedback, and that it's easy to configure from a developer perspective.

Screenshots or Videos

No response

Platform

All browsers / all OS

Additional context

I highly recommend reading Marcy Sutton's writeup on accessible client-side routing techniques which includes real user testing and actionable suggestions for improving the experience for disabled users.

[CHE1RON]

@mayank99 This is a great write-up, thanks for posting it! I guess a11y will definitely happen down the road, considering that the project is still somewhat in its infancy .. 🤷

[TheBinaryGuy]

As a temporary workaround, you could use @react-aria/live-announcer combined with static route data to announce route changes.

Here's a small PoC, not sure if it's the "right" way though:
https://github.com/TheBinaryGuy/tsr-live-announcer

Important part is the RouteAnnouncer component.