Consolidate Router State Access

[ryanflorence]

Discussed in #12358

^{Originally posted by ryanflorence November 23, 2024}
Right now you access active, pending, and transitioning states from a bunch of different hooks. This proposal hopes to consolidate them all into a simpler API.

Today

Accessing Current States

let location = useLocation()
let params = useParams()
let [searchParams] = useSearchParams()
let matches = useMatches()
let type = useNavigationType()

<NavLink to={path}>{({ isActive }) => isActive}</NavLink>

Accessing Pending States

let navigation = useNavigation()
navigation.location

// have to construct search params
let searchParams = new URLSearchParams(
  navigation.location.search,
)

// no access
let params = undefined
let type = undefined

// access to form stuff (rarely used, fetchers usually better)
navigation.formAction // etc.

<NavLink to={path}>{({ isPending }) => isPending}</NavLink>

Accessing View Transition States

let state = useViewTransitionState(to)

<NavLink to={path}>
  {({ isTransitioning }) => isTransitioning}
</NavLink>

Proposal: Consolidate into one hook

All of those hooks are either accessing active/pending states or matching against a path and providing active/pending states. We can do this with one hook.

type RouterStateVariant = {
  location: Location
  searchParams: URLSearchParams
  params: Params
  matches: Matches
}

type RouterState = {
  active: RouterStateVariant
  pending: null | RouterStateVariant
  transitioning: boolean
}

let { active, pending, transitioning } = useRouterState()

// user clicks a link, both active and pending could have values
active.location
pending.location

By providing a path to the hook, we can match against it to determine the states, and even provide better types

type RouterStateVariant<Path> = {
  location: Location<Path>
  searchParams: URLSearchParams<Path>
  params: Params<Path>
  matches: Matches<Path>
  type: NavigationType // Pop, Push, Replace
}

type RouterState<Path> = {
  active: null | RouterStateVariant<Path>
  pending: null | RouterStateVariant<Path>
  transitioning: boolean
}

let { active, pending, transitioning } =
  useRouterState('/projects/:id')

// the url is /projects/123
active.params.id
active.location // etc.
pending === null

// the url is /projects, user clicked /projects/123
active === null
pending.params.id
pending.location

Deprecations

This one hook can deprecate all eight of these:

• useLocation
• useSearchParams
• useParams
• useTransitionState
• useNavigation
• useMatches
• useMatch(pattern)
• useNavigationType

Refactor

Probably some potential refactoring to simplify the code and have the deprecated hooks (and NavLink) use the new hook underneath.

[oceandrama]

Is transitioning means also isPending from startTransition in BrowserRouter? Or it only applies to view transition? Is it possible now to get this state?

[Soviut]

I ran into this recently where I wanted the isActive state outside of a NavLink for sidebar styling. I was surprised that there was no API for this and instead had to copy the code from the NavLink component itself to get it.

react-router/packages/react-router/lib/dom/lib.tsx

Lines 858 to 862 in a3e4b8e

	let isActive =
	locationPathname === toPathname ||
	(!end &&
	locationPathname.startsWith(toPathname) &&
	locationPathname.charAt(endSlashPosition) === "/");

[slorber]

Wouldn't this trigger useless re-renders for many components using it that do not care about particular routing updates?

Here's an interactive article presenting the problem with React Router as an example: https://thisweekinreact.com/articles/useSyncExternalStore-the-underrated-react-api

---

For pending state, what are the use cases to access that in the currently rendered tree (others should be solved by [createStore() + use()]

(facebook/react#33215) later). Next.js has useLinkStatus

I wouldn't want all my useRouterState() components to re-render whenever I click on a link to trigger a transition.

[sergiodxa]

Wouldn't this trigger useless re-renders for many components using it that do not care about particular routing updates?

@slorber this already happens, because every hook in RR currently subscribe to the same React context used internally by RR, so if you do a navigation you will see that every component has at least 2 re-renders (one when navigation.state goes from idle to loading and another when it goes back to idle) even if you don't use useNavigation hook but use another RR hook.

React would need to implement some context selector to allow the current hooks to only cause a re-render when their part of the router state changes. Or RR would have to keep one context per hook with only the relevant parts and memoized to ensure any other state change won't affect that part.

[slorber]

For Docusaurus we have some documentation sites with very large sidebars where items need to be highlighted depending on the currently selected URL. Here's an example: https://xsoar.pan.dev/docs/reference/integrations/one-password

Not optimizing re-renders in this case means that when clicking on a TOC item to navigate to an anchor might lead to weird UX where the UX gets slow because a ton of unrelated elements need to re-render for no reason, so we optimize by subscribing to useHistory() directly:

function useHistorySelector(selector) {
  const history = useHistory();
  return useSyncExternalStore(history.listen, () =>
    selector(history),
  );
}

I understand this solution may not work in all situations, and it's not easy to create an optimized and convenient API today. I just wanted to expose how problematic this kind of API can be in practice for performance reasons and ensure re-renders are being considered in this decision.

Of course, we could use virtualization in our case, but that may not work well with SSG/hydration and would be overkill for the majority of doc sites that have more reasonable sidebars. I think it's legit to assume that many non-virtualized UI elements may need to read the router state for various reasons, leading to potential performance problems.

React would need to implement some context selector to allow the current hooks to only cause a re-render when their part of the router state changes.

It doesn't look like the React team plans to implement context selectors because they do not compose well, but most likely it will be something like this, IMHO:

• https://x.com/sebastienlorber/status/1925120933842276523
• https://interbolt.org/blog/react-use-selector-optimization/

Unfortunately, we don't know when any of these things will be available.

Or RR would have to keep one context per hook with only the relevant parts and memoized to ensure any other state change won't affect that part.

That could be a solution until React improves, but I assume it's not something the React Router team will want to adopt.

Couldn't you at least isolate the pending state in another context? I guess that would at least prevent the double-render issue in most cases. Most UI components likely do not care about the pending state.