The Router is the core object that manages routing state, navigation, and route matching in TanStack Router.
Creating a Router
createRouter
Creates a new Router instance for React.
import { createRouter } from '@tanstack/react-router'
const router = createRouter({
routeTree,
context: { userId: '123' },
defaultPreload: 'intent',
})
packages/react-router/src/router.ts:91
options
RouterConstructorOptions
required
Router options used to configure the router.Show RouterConstructorOptions properties
Your route definitions created with createRootRoute and child routes.
Required if the root route was created with createRootRouteWithContext. Provides context available to all routes.
defaultPreload
'intent' | 'render' | 'viewport' | boolean
default:"false"
The default preload strategy for all Link components.
'intent': Preload on hover/focus'render': Preload when link renders'viewport': Preload when link enters viewportfalse: Disable preloading
Delay in milliseconds before preloading on hover/focus.
defaultComponent
RouteComponent
default:"Outlet"
The default component a route should use if no component is provided.
defaultErrorComponent
ErrorRouteComponent
default:"ErrorComponent"
The default error component a route should use if no error component is provided.
The default pending component a route should use if no pending component is provided.
defaultNotFoundComponent
NotFoundRouteComponent
default:"NotFound"
The default notFound component a route should use if no notFound component is provided.
Wrap
(props: { children: any }) => React.JSX.Element
A component that will be used to wrap the entire router. Only non-DOM-rendering components like providers should be used.
InnerWrap
(props: { children: any }) => React.JSX.Element
A component that will be used to wrap the inner contents of the router where you also need access to the router context and hooks.
defaultOnCatch
(error: Error, errorInfo: React.ErrorInfo) => void
The default onCatch handler for errors caught by the Router ErrorBoundary.
The basepath for the router instance (e.g., ‘/app’).
Custom history implementation. By default, uses browser history.
A Router instance to be provided to RouterProvider.
Router Class
The Router class extends RouterCore from @tanstack/router-core.
Source: packages/react-router/src/router.ts:95-119
export class Router<
TRouteTree extends AnyRoute,
TTrailingSlashOption extends TrailingSlashOption = 'never',
TDefaultStructuralSharingOption extends boolean = false,
TRouterHistory extends RouterHistory = RouterHistory,
TDehydrated extends Record<string, any> = Record<string, any>,
> extends RouterCore<...> {
constructor(options: RouterConstructorOptions<...>) {
super(options)
}
}
RouterProvider
Top-level component that renders the active route matches and provides the router to the React tree via context.
import { RouterProvider } from '@tanstack/react-router'
function App() {
return <RouterProvider router={router} />
}
packages/react-router/src/RouterProvider.tsx:58-67
The router instance created with createRouter.
Additional router options to update the router instance. Accepts the same options as createRouter to update the router after creation.
Usage Example
import { createRouter, RouterProvider, createRootRoute, createRoute } from '@tanstack/react-router'
// Create routes
const rootRoute = createRootRoute({
component: () => (
<div>
<h1>My App</h1>
<Outlet />
</div>
),
})
const indexRoute = createRoute({
getParentRoute: () => rootRoute,
path: '/',
component: () => <div>Home Page</div>,
})
const aboutRoute = createRoute({
getParentRoute: () => rootRoute,
path: '/about',
component: () => <div>About Page</div>,
})
const routeTree = rootRoute.addChildren([indexRoute, aboutRoute])
// Create router
const router = createRouter({
routeTree,
defaultPreload: 'intent',
defaultPreloadDelay: 50,
})
// Provide to app
function App() {
return <RouterProvider router={router} />
}
Type Safety
To enable type-safe routing throughout your app, register your router type:
declare module '@tanstack/react-router' {
interface Register {
router: typeof router
}
}
- Route paths in
Link components
- Search params
- Route params
- Navigation options
See Also