router-query/repository-context/docs/router/api/router/useMatchesHook.md

id: useMatchesHook title: useMatches hook

The useMatches hook returns the router's complete presented array of RouteMatch objects regardless of its caller's position in the component tree. The array can include still-loading descendants or matches below a pending/error/not-found render boundary.

[!TIP] If you only want the parent or child matches, then you can use the useParentMatches or the useChildMatches based on the selection you need.

useMatches options

The useMatches hook accepts a single optional argument, an options object.

opts.select option

• Optional
• (matches: RouteMatch[]) => TSelected
• If supplied, this function will be called with the route matches and the return value will be returned from useMatches. This value will also be used to determine if the hook should re-render its parent component using shallow equality checks.

opts.structuralSharing option

• Type: boolean
• Optional
• Configures whether structural sharing is enabled for the value returned by select.
• See the Render Optimizations guide for more information.

useMatches returns

• If a select function is provided, the return value of the select function.
• If no select function is provided, an array of RouteMatch objects.

Examples

import { useMatches } from '@tanstack/react-router'

function Component() {
  const matches = useMatches()
  //     ^? [RouteMatch, RouteMatch, ...]
  // ...
}