Read the current route match
A component needs route-specific params, search data, loader data, or context from the match.
TanStack · Hook
useMatch
useMatch returns the RouteMatch for a route in the component tree. It can select a derived value and optionally allow an absent match without throwing.
How it works
useMatch reads the RouteMatch associated with a route in the component tree. Pass the route identifier through from; optionally use select to derive a smaller value, while strict controls whether the match must be associated with the specified route and shouldThrow controls behavior when no match exists.
Syntax
useMatch<TSelected = RouteMatch>(opts: { from: string; select?: (match: RouteMatch) => TSelected; strict?: boolean; shouldThrow?: boolean }): TSelectedParameters
| Name | Type | Description |
|---|---|---|
opts.from | string | Route ID identifying the match to read; the documented examples use a route path or rootRouteId. |
opts.select | (match: RouteMatch) => TSelected | Optional function receiving the RouteMatch and producing the hook's returned value. |
opts.strict | boolean | Optional strictness setting; when false, the returned match type is loosened. |
opts.shouldThrow | boolean | Optional missing-match behavior; false allows an undefined result. |
Returns
The selected value when select is supplied; otherwise the RouteMatch, or a loosened RouteMatch when strict is false. With shouldThrow: false, the result can be undefined when no match exists.
Key points
- It returns the route match visible from the calling component's location in the route tree.
- The returned match exposes the router's information for that matched route.
- Call the hook with one options object rather than separate positional arguments.
- Use
fromto specify the route ID whose match should be read. selectreceives the match and makes its return value the hook result.- Selecting a focused value lets the hook determine parent re-renders with shallow equality.
Common mistakes
- Without
select, the hook returns the complete match; settingstrictto false loosens the returned type.
Example: Select a route parameter
import { useMatch } from '@tanstack/react-router'
export function PostHeader() {
const match = useMatch({
from: '/posts/$postId',
select: (match) => match.params.postId,
})
return <h1>Post {match}</h1>
}This component reads the current post route match and selects only its post ID.
When to use it
Select a focused value
A component needs only one field and should avoid subscribing to unrelated match data.
Handle an optional match
A shared component may render outside the requested route match.
Interview questions
QWhat does useMatch provide?
useMatch returns the route match associated with the component's position in the route tree. The match includes route information and powers hooks such as parameter and loader-data hooks.
Follow-up: How can you reduce unnecessary parent re-renders? Pass a select function that returns only the needed value; the selected result is compared with shallow equality.
QHow do you select data from a match?
The hook accepts one options object. from identifies the route, while select transforms the match into the value returned by the hook.
Follow-up: What should be used when the route ID is known through a RouteApi? Use the API's pre-bound useMatch, which takes selection options without requiring from.
QHow do you handle a missing match?
With shouldThrow: false, a missing match can produce undefined, so the component should check the result before using it. The documented example narrows the value with an explicit undefined check.
Follow-up: What is the alternative default behavior? Allow the hook to throw when the requested match is unavailable, when that behavior is appropriate for the component.
Related
useParamsuseLoaderDatauseRouteContextuseSearchuseMatchesuseMatchRouteRouteApi