Read route filters
A route component needs validated query values such as filters, pagination, or sorting.
TanStack · Hook
useSearch
useSearch returns the current location's search parameters in a TanStack Router React component. Use from for route-specific typing, select for a derived value, and strict: false for a looser shared-schema view.
How it works
useSearch is a TanStack Router React hook that subscribes to the current location's search parameters. Provide a route identifier with from for precise types, optionally project the search object with select, or set strict to false for a looser shared-schema result.
Syntax
useSearch({ from, shouldThrow, select, strict })Parameters
| Name | Type | Description |
|---|---|---|
from | string | Route ID used to match the search-query parameters; required in strict mode. |
shouldThrow | boolean | Whether to throw when no matching rendered route is found; defaults to true. |
select | (search: SelectedSearchSchema) => TSelected | Transforms the search object and returns the selected value. |
strict | boolean | When false, ignores from and loosens the type to Partial<FullSearchSchema>; defaults to true. |
Returns
With from, the current location's search-parameter object, or the value returned by select. With strict: false, a Partial<FullSearchSchema> or the selected value; with shouldThrow: false and no match, undefined.
Key points
- The hook reads search parameters from the current location.
- Configuration is supplied through an options object.
- from identifies the route whose search parameters should be matched.
- select transforms the complete search object into the value exposed by the hook.
- strict: false changes the result to a partial shared search schema.
Common mistakes
- With shouldThrow set to false, a missing rendered route match does not throw; the hook returns undefined instead.
- Setting strict to false disables the from constraint and loosens the inferred search type.
Example: Read route search parameters
import { useSearch } from '@tanstack/react-router'
function Component() {
const search = useSearch({ from: '/posts/$postId' })
return <pre>{JSON.stringify(search, null, 2)}</pre>
}Reads the current route's typed search parameters and renders them.
When to use it
Select one parameter
A component needs only one derived search value instead of the full parameter object.
Read shared search state
Shared UI reads search parameters without naming a specific route origin.
Interview questions
QWhat does useSearch return, and why use from?
useSearch returns the current location's search query parameters as an object. Passing from identifies the route whose search schema should be used, providing stronger type safety.
Follow-up: How can a component subscribe to only one search value? Use select to return that value, so the hook result is the selected type and the component can avoid responding to unrelated search changes.
QHow does select change the hook result?
The select callback receives the search object and its return value becomes the hook result. For example, selecting search.postView produces a string rather than the complete search schema.
Follow-up: What trade-off does strict: false make? It omits the from requirement and exposes a Partial<FullSearchSchema>, so properties may be undefined.
QWhich options control matching and failure behavior?
The hook accepts an options object. from is required in strict mode, shouldThrow defaults to true, select is optional, and strict defaults to true.
Follow-up: What happens when a route match cannot be found? With the default shouldThrow behavior an invariant exception is thrown; setting it to false returns undefined instead.
Related
useRouterStateRoute.useSearchuseParamsuseLoaderData