Imperative navigation
A button click needs to change routes programmatically.
TanStack · Hook
useRouter
useRouter returns the current TanStack Router instance from context. Use it for imperative router operations in a component.
How it works
Call useRouter inside a component to obtain the current Router instance from context. Use that instance for imperative router operations such as navigation; if the component must react to router-state changes, use useRouterState instead.
Syntax
useRouter()Returns
The current Router instance.
Key points
- The hook obtains the active Router instance through React context.
- Use it when component code needs direct access to router functionality.
- Its return value is the current Router instance.
- Choose useRouterState when rendered output must update in response to router-state changes.
Common mistakes
- Reading router.state gives current data but does not cause the component to re-render when that state changes.
Example: Navigate imperatively
import { useRouter } from '@tanstack/react-router'
export function GoHomeButton() {
const router = useRouter()
return <button onClick={() => router.navigate({ to: '/' })}>Home</button>
}Gets the router from context and uses it for imperative navigation.
When to use it
Imperative route matching
An event handler needs to test whether a route matches.
Router instance access
Component logic needs access to router APIs or options.
Interview questions
QWhat does useRouter return and when is it useful?
useRouter is a hook that returns the current Router instance from context. It is used inside a component when imperative access to router operations is needed.
Follow-up: How should a component react to router-state changes? Use useRouterState, because router.state itself is not reactive and will not trigger re-renders.
QHow can useRouter be used for navigation?
The hook returns the current Router instance. A component can use that instance to perform imperative actions such as calling router.navigate in an event handler.
Follow-up: What alternative is appropriate for an imperative route match check? Use useRouter and call router.matchRoute.
QIs router.state reactive when obtained through useRouter?
useRouter exposes the router instance, but its state is not reactive when read directly from router.state. A component depending on state updates should use useRouterState.
Follow-up: Why is direct router.state access still useful? It provides an up-to-date snapshot for imperative code, even though it does not subscribe the component to changes.
Related
useRouterStateuseMatchRouterouter.navigaterouter.matchRoute