Derive navigation context
Build breadcrumbs or route navigation from descendant route IDs, paths, or metadata.
TanStack · Hook
useChildMatches
Returns descendant route matches from the closest match to the leaf-most match, excluding the current match. An optional selector can map those matches to another value.
How it works
useChildMatches reads the child RouteMatch objects beneath the closest matched route. It excludes the current match, while an optional select function can transform the array and influence rerendering through shallow equality; structuralSharing can control reuse of selected results.
Syntax
useChildMatches(opts?)Parameters
| Name | Type | Description |
|---|---|---|
opts | object | Optional options object containing select and structuralSharing. |
opts.select | (matches: RouteMatch[]) => TSelected | Transforms RouteMatch[] into the value returned by the hook; optional. |
opts.structuralSharing | boolean | Controls structural sharing for the value returned by select; optional. |
Returns
With select, the selected value; without select, an array of RouteMatch objects.
Key points
- It provides the descendant route matches spanning from the nearest matched route to the deepest matched route.
- Its output follows the router's current match presentation.
- select transforms the route-match array, and the transformed value becomes the hook's result.
- The selected value is compared shallowly to determine parent rerenders.
- structuralSharing controls structural sharing for the value produced by select.
Common mistakes
- The current route is excluded; use useMatch when the current match is also needed.
- The returned list may contain descendants that have not finished loading or are below the current rendering boundary.
Example: Read descendant route IDs
import { useChildMatches } from '@tanstack/react-router'
function Breadcrumbs() {
const matches = useChildMatches({
select: (routeMatches) =>
routeMatches.map((match) => match.routeId),
})
return <nav>{matches.join(' / ')}</nav>
}Selects route IDs from descendant matches and renders them as a simple breadcrumb trail.
When to use it
Project match data
Extract only the route data a component needs with select instead of processing every match during render.
Inspect nested routing state
Observe nested route state that may include descendants beyond the current render boundary.
Interview questions
QWhat does useChildMatches return?
It returns the child RouteMatch objects from the closest match down to the leaf-most match, excluding the current match. Without select, the result is an array of RouteMatch objects.
Follow-up: How can the result be transformed? Pass select, which receives RouteMatch[] and returns the value exposed by the hook.
QWhat is the purpose of select?
The select callback receives the route-match array and its return value becomes the hook result. That selected value also participates in shallow-equality checks used to decide whether the parent component should rerender.
Follow-up: What option controls reuse behavior for a selected result? structuralSharing configures whether structural sharing is enabled for the value returned by select.
QWhy might matches include loading or non-rendered descendants?
The hook's result comes from the router's current match presentation rather than only from fully settled descendants. Consequently, still-loading descendants and descendants below the current render boundary may appear.
Follow-up: How would you obtain the current match instead? Use useMatch, because useChildMatches deliberately omits the current match.
Related
useMatchuseParentMatchesRouteMatch