Track router status
A component needs to react to router-wide state changes such as navigation status.
TanStack · Hook
useRouterState
A reactive hook for reading TanStack Router's internal state in a component. An optional selector can reduce the returned value to the specific state needed.
How it works
useRouterState subscribes a component to the router's internal state. Without options it returns the complete RouterState; with select, it derives a value from that state, and structuralSharing can control sharing for the selected result.
Syntax
useRouterState(options?)Parameters
| Name | Type | Description |
|---|---|---|
opts | UseRouterStateOptions<TSelected> | Optional selector and structural-sharing configuration. select receives RouterState and returns the selected value; structuralSharing controls sharing for that value. |
opts.select | (state: RouterState) => TSelected | Transforms RouterState into the value returned by the hook. |
opts.structuralSharing | boolean | Controls whether structural sharing is enabled for the selected result. |
Returns
The current RouterState, or TSelected when a select function is provided.
Key points
- It provides a component with the router's current internal state.
- Use it when a component needs router state reactively.
- Call it with no argument for the whole state or pass options to select a result.
- The selector receives RouterState and its result becomes the hook's return value.
- Use structuralSharing to configure sharing behavior for selected results.
- The return type is RouterState without select, otherwise it is the selector's TSelected type.
Common mistakes
- Prefer useLocation or useMatches for location or match data; they are intended to be more ergonomic and performant than reading the full router state.
- Do not read router.state directly in a component when it must re-render after router-state changes; use this hook for a reactive value.
Example: Read a selected router value
import { useRouterState } from '@tanstack/react-router'
export function RouterStatus() {
const status = useRouterState({
select: (state) => state.status,
})
return <output>{status}</output>
}This component subscribes to the router and renders only the selected navigation status.
When to use it
Select a focused value
A component needs one derived value rather than the complete RouterState object.
Subscribe to router changes
A component needs reactive router state instead of a direct, non-reactive router.state read.
Interview questions
QWhat does useRouterState return?
It is a hook that exposes the router's current internal state to a component. It returns RouterState by default, or the value produced by select when a selector is supplied.
Follow-up: How would you avoid subscribing to more state than necessary? Pass select and return only the field or derived value the component needs.
QWhat options does the hook accept?
The options object is optional. Its select callback receives RouterState and determines the returned value; structuralSharing configures whether structural sharing is enabled for that selected value.
Follow-up: What should a component use for current location data instead? Prefer useLocation, which is designed specifically for that access pattern.
QWhy use this hook instead of router.state?
router.state is current but non-reactive when accessed directly in a component, so a component will not re-render when it changes. useRouterState provides the reactive version.
Follow-up: When only route matches are needed, which specialized hook is preferable? Use useMatches rather than accessing the complete router state.
Related
useLocationuseMatchesuseRouterRouterState