Skip to main content

​
Router

The core Router class manages routing state, navigation, and route matching in TanStack Router.

​
RouterOptions

Configuration options for creating a router instance.
​
routeTree
AnyRoute
required
The root route tree structure that defines all routes in your application.
​
history
RouterHistory
The history object that manages browser history. If not provided, a new createBrowserHistory instance will be created.See: History Types Guide
​
basepath
string
The base path for the router. All routes will be relative to this path.Default: '/'
​
stringifySearch
SearchSerializer
Function to stringify search params when generating links.Default: defaultStringifySearch
​
parseSearch
SearchParser
Function to parse search params when parsing the current location.Default: defaultParseSearch
​
defaultPreload
false | 'intent' | 'viewport' | 'render'
Default preloading strategy for routes:
  • false - Routes are not preloaded
  • 'intent' - Preload on hover or touchstart
  • 'viewport' - Preload when in viewport
  • 'render' - Preload when rendered
Default: false
​
defaultPreloadDelay
number
Delay in milliseconds before preloading a route.Default: 50
​
defaultComponent
RouteComponent
Default component to render when a route doesn’t have a component defined.
​
defaultErrorComponent
ErrorRouteComponent
Default error component to render when a route throws an error.
​
defaultPendingComponent
RouteComponent
Default pending component to show while a route is loading.
​
defaultPendingMs
number
Minimum time in milliseconds to show pending component.Default: 1000
​
defaultPendingMinMs
number
Minimum time in milliseconds to keep pending component visible once shown.Default: 500
​
context
AnyContext
Global context object available to all routes.
​
trailingSlash
'always' | 'never' | 'preserve'
How to handle trailing slashes in URLs:
  • 'always' - Always add trailing slash
  • 'never' - Always remove trailing slash
  • 'preserve' - Keep trailing slash as-is
Default: 'never'
​
notFoundMode
'fuzzy' | 'root'
Where to render the not found component:
  • 'fuzzy' - Render at the nearest parent route
  • 'root' - Render at the root route
Default: 'fuzzy'
​
caseSensitive
boolean
Whether route matching should be case-sensitive.Default: false

​
Router Class

​
Properties

​
state
RouterState
Current router state including location, matches, and status.
​
history
RouterHistory
The history object managing navigation.
​
basepath
string
The base path for all routes.
​
routeTree
AnyRoute
The root route tree structure.

​
Methods

​
navigate
(options: NavigateOptions) => Promise<void>
Navigate to a new location.
router.navigate({
  to: '/posts/$postId',
  params: { postId: '123' },
  search: { page: 1 }
})
​
buildLocation
(options: BuildLocationOptions) => ParsedLocation
Build a location object from navigation options without navigating.
const location = router.buildLocation({
  to: '/posts',
  search: { filter: 'recent' }
})
​
matchRoute
(location: ParsedLocation, options?: MatchRouteOptions) => RouteMatch | false
Check if a location matches a route.
const match = router.matchRoute({ to: '/posts' })
if (match) {
  console.log('Route matches!', match)
}
​
preloadRoute
(options: NavigateOptions) => Promise<RouteMatch[]>
Preload a route and its data.
await router.preloadRoute({
  to: '/posts/$postId',
  params: { postId: '123' }
})
​
invalidate
() => Promise<void>
Invalidate and refetch all active route matches.
await router.invalidate()
​
load
() => Promise<void>
Load or reload the current route matches.
​
subscribe
(eventName: string, callback: Function) => () => void
Subscribe to router events. Returns an unsubscribe function.
const unsubscribe = router.subscribe('onLoad', () => {
  console.log('Route loaded')
})

​
RouterState

The current state of the router.
​
location
ParsedLocation
The current location object.
​
matches
RouteMatch[]
Array of matched routes for the current location.
​
pendingMatches
RouteMatch[]
Array of matches that are currently loading.
​
status
'pending' | 'idle'
Current navigation status.
​
isLoading
boolean
Whether the router is currently loading a route.
​
isTransitioning
boolean
Whether the router is currently transitioning between routes.

​
Example Usage

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

// Define routes
const rootRoute = createRootRoute()

const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/',
  component: () => <div>Home</div>
})

const routeTree = rootRoute.addChildren([indexRoute])

// Create router
const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
  defaultPendingMs: 1000
})

// Navigate programmatically
await router.navigate({
  to: '/about',
  search: { tab: 'overview' }
})

// Subscribe to events
const unsubscribe = router.subscribe('onLoad', (event) => {
  console.log('Navigation completed', event)
})

​
Type Safety

Register your router for full type safety across your application: 
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us