Navigate after an async side effect
A successful form submission or mutation should move the user to another route.
TanStack · Hook
useNavigate
useNavigate returns an imperative navigation function for a TanStack Router application. Use it to change the pathname, search parameters, hash, or location state, especially when navigation is triggered by component logic.
How it works
In a React component, call useNavigate with an optional source location to obtain an imperative navigation function. Invoke that function with NavigateOptions to change the pathname, search parameters, hash, or location state; it returns a promise that resolves after navigation completes.
Syntax
useNavigate(opts?: { from?: string }): (options: NavigateOptions) => Promise<void>Parameters
| Name | Type | Description |
|---|---|---|
opts | object | Optional object configuring the hook; its from property is a string identifying the location to navigate from. |
options | NavigateOptions | A navigation configuration object, including destination and supported location updates. |
Returns
A navigate function; calling it returns a Promise that resolves when navigation is complete.
Key points
- Calling the hook gives the component an imperative navigation function.
- Navigation can update the path, query-like search parameters, URL hash, or location state.
- The hook's argument is one optional configuration object.
- The
fromoption establishes the source location used to resolve navigation. - Call the returned function with one navigation-options object.
- The returned promise signals that navigation has completed.
Common mistakes
- Prefer Link for ordinary user-triggered navigation; use this hook when navigation must happen imperatively, such as after a side effect.
Example: Update search parameters
import { useNavigate } from '@tanstack/react-router'
function PostsPage() {
const navigate = useNavigate({ from: '/posts' })
return (
<button onClick={() => navigate({ search: { page: 2 } })}>
Next page
</button>
)
}This component creates a navigate function scoped from /posts and uses it to update the page search parameter.
When to use it
Update search parameters
A pagination, filtering, or sorting control needs to update URL state from an event handler.
Imperative location updates
A component must change the hash or location state without using a declarative link.
Interview questions
QWhat does useNavigate provide?
useNavigate is a hook that returns a navigate function for changing the current location. The navigation can modify the pathname, search parameters, hash, and location state.
Follow-up: How can navigation be scoped to a route? Pass the route location through the hook's optional from option, such as useNavigate({ from: '/posts' }).
QWhat is the purpose of the from option?
The hook accepts an optional options object. Its from string identifies the location to navigate from, which is useful when the target should be resolved relative to a specific location rather than the current one.
Follow-up: What does the returned function accept? One options object of type NavigateOptions, containing the destination and other navigation settings.
QWhat are the input and result of the navigate function?
The returned navigate function accepts one NavigateOptions object and performs the requested navigation. Its result is a promise that resolves when navigation finishes.
Follow-up: How would you update only a search parameter? Invoke navigate with a search option, for example navigate({ search: { page: 2 } }).
Related
LinkNavigateOptionsuseSearchuseParamsRouteApi