Match API

Match

Route matches represent active route segments in the current navigation, containing their data, status, and metadata.

RouteMatch

An individual route match in the current location.

id · string

Unique identifier for this match instance.

routeId · string

The ID of the route that was matched.

fullPath · string

The complete path for this route including parent paths.

pathname · string

The actual pathname portion of the URL that matched this route.

params · Record<string, any>

Path parameters extracted for this match.

// For route /posts/$postId
match.params.postId // '123'

status · 'pending' | 'success' | 'error' | 'redirected' | 'notFound'

Current status of the match.

isFetching · false | 'beforeLoad' | 'loader'

Whether the match is currently fetching data, and which phase.

error · unknown

Error thrown by the loader or beforeLoad function.

updatedAt · number

Timestamp when the match was last updated.

loaderData · any

Data returned from the route’s loader function.

context · Record<string, any>

Combined context from this route and all parent routes.

search · Record<string, any>

Validated search parameters for this match.

index · number

The index of this match in the matches array (0 is root).

Match Component

Render a specific route match component.

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

function CustomLayout() {
  return (
    <div>
      <Sidebar />
      <Match 
        from="/posts" 
        component={PostsLayout}
      />
    </div>
  )
}

Match Props

from · string · required

The route ID to match.

component · RouteComponent

Component to render for the match.

errorComponent · ErrorRouteComponent

Component to render if the match has an error.

pendingComponent · RouteComponent

Component to render while the match is pending.

Outlet Component

Render child route matches.

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

function Layout() {
  return (
    <div>
      <Header />
      <main>
        <Outlet />
      </main>
      <Footer />
    </div>
  )
}

useMatches Hook

Access all current route matches.

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

function Breadcrumbs() {
  const matches = useMatches()
  
  return (
    <nav>
      {matches.map((match, i) => (
        <span key={match.id}>
          {i > 0 && ' > '}
          {match.staticData?.title || match.routeId}
        </span>
      ))}
    </nav>
  )
}

useMatches Options

select · (matches: RouteMatch[]) => any

Select specific data from the matches.

const titles = useMatches({
  select: (matches) => matches.map(m => m.staticData?.title)
})

strict · boolean

Throw error if used outside RouterProvider.

Default: true

useParentMatches Hook

Access matches for parent routes only.

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

function RouteInfo() {
  const parentMatches = useParentMatches()
  
  return (
    <div>
      <h3>Parent Routes</h3>
      <ul>
        {parentMatches.map(match => (
          <li key={match.id}>{match.routeId}</li>
        ))}
      </ul>
    </div>
  )
}

useChildMatches Hook

Access matches for child routes only.

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

function NestedNav() {
  const childMatches = useChildMatches()
  
  if (childMatches.length === 0) {
    return null
  }
  
  return (
    <nav>
      {childMatches.map(match => (
        <a key={match.id} href={match.pathname}>
          {match.staticData?.title}
        </a>
      ))}
    </nav>
  )
}

useMatch Hook

Access a specific route match with full type safety.

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

function PostDetails() {
  const match = useMatch({
    from: '/posts/$postId',
    strict: true
  })
  
  return (
    <div>
      <h1>Post ID: {match.params.postId}</h1>
      <p>Status: {match.status}</p>
    </div>
  )
}

useMatch Options

from · string

The route ID to match. Enables type safety.

from: '/posts/$postId'

strict · boolean

Throw error if route is not matched.

Default: true

select · (match: RouteMatch) => any

Select specific data from the match.

const postId = useMatch({
  from: '/posts/$postId',
  select: (match) => match.params.postId
})

MatchRoute Component

Conditionally render based on route match.

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

function Navigation() {
  return (
    <nav>
      <Link to="/">Home</Link>
      
      <MatchRoute to="/admin" params>
        {(match) => (
          match ? <AdminNav /> : null
        )}
      </MatchRoute>
    </nav>
  )
}

MatchRoute Props

to · string · required

The path to match against.

params · boolean | Record<string, any>

Match with specific params or any params.

pending · boolean

Match pending routes.

caseSensitive · boolean

Use case-sensitive matching.

children · (match: RouteMatch | false) => ReactNode

Render function receiving the match or false.

useMatchRoute Hook

Programmatically check if a route matches.

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

function Header() {
  const matchRoute = useMatchRoute()
  
  const isPostsPage = matchRoute({ to: '/posts' })
  const isPostDetail = matchRoute({ to: '/posts/$postId' })
  
  return (
    <header>
      {isPostsPage && <PostsHeader />}
      {isPostDetail && <PostDetailHeader />}
    </header>
  )
}

useMatchRoute Options

to · string · required

The path to match.

params · Record<string, any>

Params that must match.

matchRoute({
  to: '/posts/$postId',
  params: { postId: '123' }
})

pending · boolean

Check pending matches instead of current matches.

caseSensitive · boolean

Use case-sensitive matching.

includeSearch · boolean

Include search params in matching.

fuzzy · boolean

Allow fuzzy matching (match child routes).

Default: true

Examples

Breadcrumb Navigation

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

function Breadcrumbs() {
  const matches = useMatches()
  
  return (
    <nav aria-label="breadcrumb">
      <ol className="breadcrumb">
        {matches.map((match, index) => (
          <li key={match.id}>
            {index < matches.length - 1 ? (
              <Link to={match.pathname}>
                {match.staticData?.title || match.routeId}
              </Link>
            ) : (
              <span>{match.staticData?.title || match.routeId}</span>
            )}
          </li>
        ))}
      </ol>
    </nav>
  )
}

Conditional Rendering

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

function Sidebar() {
  const matchRoute = useMatchRoute()
  
  const showUserMenu = matchRoute({ 
    to: '/dashboard', 
    fuzzy: true 
  })
  
  const showAdminMenu = matchRoute({ 
    to: '/admin',
    fuzzy: true
  })
  
  return (
    <aside>
      {showUserMenu && <UserMenu />}
      {showAdminMenu && <AdminMenu />}
    </aside>
  )
}

Match Status Handling

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

function PostView() {
  const match = useMatch({ from: '/posts/$postId' })
  
  if (match.status === 'pending') {
    return <LoadingSpinner />
  }
  
  if (match.status === 'error') {
    return <ErrorMessage error={match.error} />
  }
  
  const post = match.loaderData
  
  return <Post post={post} />
}

Route Context Access

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

function ThemeToggle() {
  // Get theme from any parent route's context
  const theme = useMatches({
    select: (matches) => {
      // Find first match with theme in context
      const matchWithTheme = matches.find(
        m => m.context.theme
      )
      return matchWithTheme?.context.theme || 'light'
    }
  })
  
  return <button>Current theme: {theme}</button>
}