Route

Route API

Routes define the URL structure, data loading, and rendering for your application.

createRoute

Creates a non-root Route instance for code-based routing.

import { createRoute } from '@tanstack/react-router'
import { rootRoute } from './root'

const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/posts',
  component: PostsComponent,
})

Parameters

options · RouteOptions · required

Route configuration options.

Show properties

getParentRoute · () => Route · required

A function that returns the parent route. Required for non-root routes.

path · string · required

The path segment for this route. Can include path parameters like $postId.

id · string

A custom ID for the route. If not provided, one will be generated from the path.

component · RouteComponent

The component to render for this route.

errorComponent · ErrorRouteComponent

The component to render when an error occurs in this route.

pendingComponent · RouteComponent

The component to render while the route is loading.

notFoundComponent · NotFoundRouteComponent

The component to render when this route doesn’t match.

loader · LoaderFn

A function that loads data for the route.

loader: async ({ params }) => {
  const post = await fetchPost(params.postId)
  return { post }
}

beforeLoad · BeforeLoadFn

A function that is called before the route is loaded. Can be used for authentication checks.

beforeLoad: async ({ context }) => {
  if (!context.user) {
    throw redirect({ to: '/login' })
  }
}

validateSearch · SearchValidator

A function or schema to validate and parse search parameters.

validateSearch: (search) => ({
  page: Number(search.page) || 1,
  filter: search.filter || 'all',
})

loaderDeps · (opts: { search }) => any

A function that returns dependencies for the loader. Changes trigger a reload.

loaderDeps: ({ search }) => ({ page: search.page })

context · RouteContextFn

A function that returns additional context for this route and its children.

context: ({ params }) => ({
  postId: params.postId,
})

staleTime · number

The time in milliseconds that the route’s data will be considered fresh.

gcTime · number

The time in milliseconds that the route’s data will be kept in the cache after it becomes unused.

pendingMs · number

The minimum time in milliseconds before the pending component is shown.

pendingMinMs · number

The minimum time in milliseconds that the pending component will be shown once it appears.

preload · boolean

If true, this route will be preloaded when it enters the viewport or on intent.

preloadStaleTime · number

The time in milliseconds that preloaded data will be considered fresh.

shouldReload · boolean | ((args) => boolean)

Controls whether the route should reload when navigated to.

Returns

route · Route

A Route instance to be attached to the route tree.

Route Methods

Route instances expose several type-safe methods for use in components:

route.useMatch()

Get the current route match data.

function Component() {
  const match = postsRoute.useMatch()
  return <div>{match.status}</div>
}

route.useParams()

Access the route’s path parameters.

function Component() {
  const { postId } = postRoute.useParams()
  return <div>Post ID: {postId}</div>
}

route.useSearch()

Access the route’s search parameters.

function Component() {
  const { page, filter } = postsRoute.useSearch()
  return <div>Page {page}</div>
}

route.useLoaderData()

Access the route’s loader data.

function Component() {
  const { post } = postRoute.useLoaderData()
  return <h1>{post.title}</h1>
}

route.useLoaderDeps()

Access the route’s loader dependencies.

function Component() {
  const deps = postsRoute.useLoaderDeps()
  return <div>Page: {deps.page}</div>
}

route.useNavigate()

Get a navigate function pre-bound to this route.

function Component() {
  const navigate = postRoute.useNavigate()
  return <button onClick={() => navigate({ to: '..' })}>Back</button>
}

route.useRouteContext()

Access the route’s context.

function Component() {
  const context = postRoute.useRouteContext()
  return <div>{context.postId}</div>
}

route.Link

A pre-bound Link component for this route.

function Component() {
  return (
    <postRoute.Link params={{ postId: '123' }}>
      View Post
    </postRoute.Link>
  )
}

createRouteMask

Create a route mask for displaying a route at a different path.

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

const photoModalMask = createRouteMask({
  routeTree,
  from: '/photos/$photoId',
  to: '/photos',
  params: true,
})

Parameters

options · object · required

Show properties

routeTree · AnyRoute · required

The route tree to create the mask for.

from · string · required

The route path to mask from.

to · string · required

The route path to mask to (what will be shown in the URL).

params · boolean | object

Parameters to include in the masked URL. Use true to include all params.

search · boolean | object

Search parameters to include in the masked URL. Use true to include all search params.

hash · boolean | string

Hash to include in the masked URL. Use true to include the current hash.

unmaskOnReload · boolean

If true, the mask will be removed when the page is reloaded.

Returns

routeMask · RouteMask

A route mask object to pass to the router’s routeMasks option.

Component Types

RouteComponent

A standard route component type.

import type { RouteComponent } from '@tanstack/react-router'

const MyComponent: RouteComponent = () => {
  return <div>Hello</div>
}

ErrorRouteComponent

An error boundary component type with error props.

import type { ErrorRouteComponent } from '@tanstack/react-router'

const ErrorComponent: ErrorRouteComponent = ({ error }) => {
  return <div>Error: {error.message}</div>
}

NotFoundRouteComponent

A not-found component type with routing props.

import type { NotFoundRouteComponent } from '@tanstack/react-router'

const NotFound: NotFoundRouteComponent = () => {
  return <div>Page not found</div>
}