Route API

Route

Routes define the structure of your application and handle data loading, rendering, and error handling.

Route Options

Configuration options for creating a route.

path · string

The path pattern for the route. Supports path params using $param syntax.

path: '/posts/$postId'
path: '/files/$'

id · string

Custom route ID. If not provided, generated from the path.

getParentRoute · () => Route · required

Function that returns the parent route.

getParentRoute: () => rootRoute

component · RouteComponent

Component to render for this route.

component: () => <PostsList />

errorComponent · ErrorRouteComponent

Component to render when the route throws an error.

errorComponent: ({ error }) => <ErrorPage error={error} />

pendingComponent · RouteComponent

Component to render while the route is loading.

pendingComponent: () => <LoadingSpinner />

notFoundComponent · NotFoundRouteComponent

Component to render when a child route is not found.

loader · LoaderFn

Function to load data for the route.

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

beforeLoad · BeforeLoadFn

Function that runs before the loader. Useful for authentication and redirects.

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

validateSearch · SearchValidator

Validator for search parameters. Can use Zod, Valibot, or custom validators.

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

params · ParamsOptions

Configuration for parsing and stringifying path params.

params: {
  parse: (params) => ({
    postId: Number(params.postId)
  }),
  stringify: (params) => ({
    postId: String(params.postId)
  })
}

context · RouteContextFn

Function to create additional context for this route and its children.

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

onCatch · (error: Error) => void

Error boundary handler for the route.

onError · (error: Error) => void

Called when the route encounters an error.

staticData · Record<string, any>

Static metadata for the route (e.g., for generating sitemaps).

staticData: {
  title: 'Blog Posts',
  description: 'View all blog posts'
}

staleTime · number

Time in milliseconds before cached loader data is considered stale.

Default: 0

gcTime · number

Time in milliseconds before inactive cached data is garbage collected.

Default: 30 minutes

preload · boolean

Whether to preload this route’s data.

Default: true

preloadStaleTime · number

Time in milliseconds before preloaded data is considered stale.

Route Class

Properties

id · string

The unique identifier for this route.

path · string

The path pattern for this route.

fullPath · string

The complete path including all parent paths.

options · RouteOptions

The configuration options for this route.

Methods

addChildren · (children: Route[]) => Route

Add child routes to this route.

const routeTree = rootRoute.addChildren([
  indexRoute,
  postsRoute,
  aboutRoute
])

update · (options: PartialRouteOptions) => Route

Update route options.

route.update({
  component: NewComponent
})

Creating Routes

Root Route

Every router needs a root route:

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

const rootRoute = createRootRoute({
  component: () => (
    <div>
      <Header />
      <Outlet />
      <Footer />
    </div>
  )
})

Standard Routes

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

const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/posts',
  loader: async () => {
    const posts = await fetchPosts()
    return { posts }
  },
  component: () => {
    const { posts } = postsRoute.useLoaderData()
    return <PostsList posts={posts} />
  }
})

File-based Routes

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

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    const post = await fetchPost(params.postId)
    return { post }
  },
  component: PostComponent
})

function PostComponent() {
  const { post } = Route.useLoaderData()
  return <Post post={post} />
}

Loader Context

The loader function receives a context object:

params · Record<string, any>

Path parameters extracted from the URL.

search · Record<string, any>

Validated search parameters.

context · AnyContext

Combined context from parent routes and global context.

location · ParsedLocation

The current location object.

abortController · AbortController

Controller to cancel ongoing async operations.

preload · boolean

Whether this loader is being called for preloading.

Route Hooks

Routes provide hooks for accessing route-specific data:

// Get loader data
const data = Route.useLoaderData()

// Get route params
const params = Route.useParams()

// Get search params
const search = Route.useSearch()

// Get route context
const context = Route.useRouteContext()

// Navigate from within a route
const navigate = Route.useNavigate()

Route Masking

Create virtual routes that display different content:

const maskRoute = createRouteMask({
  routeTree,
  from: '/posts/$postId',
  to: '/p/$postId',
  params: (prev) => ({
    postId: prev.postId
  })
})

Example: Complete Route

import { createRoute, redirect } from '@tanstack/react-router'
import { z } from 'zod'

const postRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/posts/$postId',
  
  // Validate search params
  validateSearch: z.object({
    page: z.number().default(1),
    tab: z.enum(['overview', 'comments']).default('overview')
  }),
  
  // Parse path params
  params: {
    parse: (params) => ({
      postId: Number(params.postId)
    }),
    stringify: (params) => ({
      postId: String(params.postId)
    })
  },
  
  // Authentication check
  beforeLoad: async ({ context }) => {
    if (!context.user) {
      throw redirect({ to: '/login' })
    }
  },
  
  // Load data
  loader: async ({ params, context, abortController }) => {
    const post = await fetchPost(params.postId, {
      signal: abortController.signal
    })
    
    if (!post) {
      throw notFound()
    }
    
    return { post }
  },
  
  // Main component
  component: PostComponent,
  
  // Error handling
  errorComponent: ({ error }) => (
    <div>Error loading post: {error.message}</div>
  ),
  
  // Loading state
  pendingComponent: () => <LoadingSpinner />,
  
  // Cache configuration
  staleTime: 5000,
  gcTime: 30 * 60 * 1000
})

function PostComponent() {
  const { post } = postRoute.useLoaderData()
  const { tab } = postRoute.useSearch()
  
  return (
    <div>
      <h1>{post.title}</h1>
      {tab === 'overview' ? (
        <PostOverview post={post} />
      ) : (
        <PostComments postId={post.id} />
      )}
    </div>
  )
}