Build breadcrumbs
A layout or root component needs route metadata for breadcrumbs or navigation.
TanStack · Hook
useMatches
useMatches returns the router’s complete presented route-match list from any component-tree position. An optional selector can transform that list into a derived result.
How it works
useMatches exposes the router’s complete presented route-match array from any component-tree position. Pass an optional selector to return a derived value instead; the selected result participates in shallow-equality checks, and structural sharing can be configured for it.
Syntax
useMatches(opts?)Parameters
| Name | Type | Description |
|---|---|---|
opts | object | Optional options object. It may contain select and structuralSharing. |
opts.select | (matches: RouteMatch[]) => TSelected | Optional function receiving the route matches and returning the selected value. |
opts.structuralSharing | boolean | Optional flag controlling structural sharing for the selected value. |
Returns
With select, the selected value; without select, an array of RouteMatch objects.
Key points
- The hook provides the full presented route-match array, independent of the caller’s location in the component tree.
- A component can access the complete match presentation without being located within a particular matched route.
- Its only argument is optional and is an options object.
- The select callback transforms the matches into the hook’s returned value.
- A selected result is used in shallow-equality checks that govern parent re-rendering.
- The structuralSharing option controls structural sharing for selected output.
Common mistakes
- Do not assume every returned match is fully loaded or above the currently rendered boundary.
Example: Render route breadcrumbs
import { useMatches } from '@tanstack/react-router'
export function Breadcrumbs() {
const matches = useMatches({
select: (matches) =>
matches.filter((match) => match.staticData?.getTitle),
})
return (
<nav>
{matches.map((match) => (
<span key={match.id}>{match.staticData.getTitle()}</span>
))}
</nav>
)
}Selects only matches that provide a static title, then renders those titles as breadcrumbs.
When to use it
Compute route-driven UI state
A shared component must derive a boolean or subset from all active matches.
Observe the complete match presentation
A component needs to inspect loading, error, or not-found match presentation.
Interview questions
QWhat does useMatches return?
useMatches returns the router’s complete presented array of RouteMatch objects, regardless of where the calling component sits in the component tree. Without a selector, the result is an array of RouteMatch objects.
Follow-up: How would you obtain only ancestors? Use useParentMatches, which is intended for parent-match selection rather than the complete match list.
QHow can useMatches return derived data?
The hook accepts one optional options object. Its select function receives the route matches and returns the value exposed by the hook, which can be a derived value such as filtered metadata.
Follow-up: Why use select instead of filtering after the hook returns? Selection lets the hook use shallow equality checks on the selected result to decide whether the parent should re-render.
QWhat does structuralSharing configure?
structuralSharing is an optional boolean in the options object. It controls whether structural sharing is enabled for the value returned by select.
Follow-up: What should a component do if it needs only child matches? Use useChildMatches rather than retrieving the full array and filtering it manually.
Related
useParentMatchesuseChildMatchesRouteMatchuseRouterState