Overview TanStack Router is a fully type-safe router for React (and Solid) applications. It provides file-based routing, first-class search parameter management, built-in data loading, code splitting, and deep TypeScript integration. It serves as the routing foundation for TanStack Start (the full-stack framework). Package: @tanstack/react-router CLI: @tanstack/router-cli or @tanstack/router-plugin (Vite/Rspack/Webpack) Devtools: @tanstack/react-router-devtools Installation npm install @tanstack/react-router

For file-based routing with Vite:

npm install -D @tanstack/router-plugin

Or standalone CLI:

npm install -D @tanstack/router-cli Core Concepts Route Trees Routes are organized in a tree structure. The root route is the top-level layout, and child routes nest underneath. import { createRootRoute , createRoute , createRouter } from '@tanstack/react-router' const rootRoute = createRootRoute ( { component : RootLayout , } ) const indexRoute = createRoute ( { getParentRoute : ( ) => rootRoute , path : '/' , component : HomePage , } ) const aboutRoute = createRoute ( { getParentRoute : ( ) => rootRoute , path : '/about' , component : AboutPage , } ) const routeTree = rootRoute . addChildren ( [ indexRoute , aboutRoute ] ) const router = createRouter ( { routeTree } ) File-Based Routing File-based routing automatically generates the route tree from your file structure. Configure with Vite plugin: // vite.config.ts import { defineConfig } from 'vite' import { TanStackRouterVite } from '@tanstack/router-plugin/vite' export default defineConfig ( { plugins : [ TanStackRouterVite ( ) , // ... other plugins ] , } ) File Naming Conventions File Pattern Route Type Example Path __root.tsx Root layout N/A (wraps all) index.tsx Index route / about.tsx Static route /about $postId.tsx Dynamic param /posts/$postId posts.tsx Layout route /posts/ (layout) posts/index.tsx Nested index /posts posts/$postId.tsx Nested dynamic /posts/123 posts_.$postId.tsx Pathless layout /posts/123 (different layout) _layout.tsx Pathless layout N/A (groups routes) _layout/dashboard.tsx Grouped route /dashboard $.tsx Splat/catch-all / posts.$postId.edit.tsx Dot notation /posts/123/edit Special Prefixes _ prefix: Pathless routes (layout groups without URL segment) $ prefix: Dynamic path parameters (folder) parentheses: Route groups (organizational, no URL impact) Route Configuration Each route can define: // routes/posts.$postId.tsx import { createFileRoute } from '@tanstack/react-router' export const Route = createFileRoute ( '/posts/$postId' ) ( { // Validation for path params params : { parse : ( params ) => ( { postId : Number ( params . postId ) } ) , stringify : ( params ) => ( { postId : String ( params . postId ) } ) , } , // Search params validation validateSearch : ( search : Record < string , unknown

) => { return { page : Number ( search . page ?? 1 ) , filter : ( search . filter as string ) || '' , } } , // Data loading loader : async ( { params , context , abortController } ) => { return fetchPost ( params . postId ) } , // Loader dependencies (re-run loader when these change) loaderDeps : ( { search } ) => ( { page : search . page } ) , // Stale time for cached loader data staleTime : 5_000 , // Preloading preloadStaleTime : 30_000 , // Error component errorComponent : PostErrorComponent , // Pending/loading component pendingComponent : PostLoadingComponent , // 404 component notFoundComponent : PostNotFoundComponent , // Before load hook (authentication, redirects) beforeLoad : async ( { context , location } ) => { if ( ! context . auth . isAuthenticated ) { throw redirect ( { to : '/login' , search : { redirect : location . href } , } ) } } , // Head/meta management head : ( ) => ( { meta : [ { title : 'Post Details' } ] , } ) , // Component component : PostComponent , } ) function PostComponent ( ) { const { postId } = Route . useParams ( ) const post = Route . useLoaderData ( ) const { page , filter } = Route . useSearch ( ) return < div

{ post . title } </ div

} Data Loading Route Loaders export const Route = createFileRoute ( '/posts' ) ( { loader : async ( { context } ) => { // Access router context (e.g., queryClient) const posts = await context . queryClient . ensureQueryData ( { queryKey : [ 'posts' ] , queryFn : fetchPosts , } ) return { posts } } , component : PostsComponent , } ) function PostsComponent ( ) { const { posts } = Route . useLoaderData ( ) // ... } Loader Dependencies Control when loaders re-execute: export const Route = createFileRoute ( '/posts' ) ( { loaderDeps : ( { search : { page , filter } } ) => ( { page , filter } ) , loader : async ( { deps : { page , filter } } ) => { return fetchPosts ( { page , filter } ) } , } ) Deferred Data Loading Stream non-critical data: import { Await , defer } from '@tanstack/react-router' export const Route = createFileRoute ( '/dashboard' ) ( { loader : async ( ) => { const criticalData = await fetchCriticalData ( ) const deferredData = defer ( fetchSlowData ( ) ) return { criticalData , deferredData } } , component : DashboardComponent , } ) function DashboardComponent ( ) { const { criticalData , deferredData } = Route . useLoaderData ( ) return ( < div

< CriticalSection data = { criticalData } /> < Suspense fallback = { < Loading /> }

< Await promise = { deferredData }

{ ( data ) => < SlowSection data = { data } /> } </ Await

</ Suspense

</ div

) } Context-Based Data Loading Provide shared dependencies via router context: // Create router with context const router = createRouter ( { routeTree , context : { queryClient , auth : undefined ! , // Will be provided by RouterProvider } , } ) // In root/app component function App ( ) { const auth = useAuth ( ) return < RouterProvider router = { router } context = { { auth } } /> } // In routes export const Route = createFileRoute ( '/protected' ) ( { beforeLoad : ( { context } ) => { if ( ! context . auth . user ) throw redirect ( { to : '/login' } ) } , loader : ( { context } ) => { return context . queryClient . ensureQueryData ( userQueryOptions ( ) ) } , } ) Search Parameters Validation import { z } from 'zod' const postSearchSchema = z . object ( { page : z . number ( ) . default ( 1 ) , filter : z . string ( ) . default ( '' ) , sort : z . enum ( [ 'date' , 'title' ] ) . default ( 'date' ) , } ) export const Route = createFileRoute ( '/posts' ) ( { validateSearch : postSearchSchema , // Or manual validation: // validateSearch: (search) => postSearchSchema.parse(search), } ) Reading Search Params function PostsComponent ( ) { // From route const { page , filter , sort } = Route . useSearch ( ) // Or from any component with useSearch hook const search = useSearch ( { from : '/posts' } ) } Updating Search Params import { useNavigate } from '@tanstack/react-router' function Pagination ( ) { const navigate = useNavigate ( ) const { page } = Route . useSearch ( ) return ( < button onClick = { ( ) => navigate ( { search : ( prev ) => ( { ... prev , page : prev . page + 1 } ) , } ) }

Next Page </ button

) } // Or via Link component < Link to = " /posts " search = { ( prev ) => ( { ... prev , page : 2 } ) }

Page 2 </ Link

Search Param Options const router = createRouter ( { routeTree , // Custom serialization search : { strict : true , // Reject unknown params } , // Default search param serializer stringifySearch : defaultStringifySearch , parseSearch : defaultParseSearch , } ) Navigation Link Component import { Link } from '@tanstack/react-router' // Static route < Link to = " /about "

About </ Link

// Dynamic route with params < Link to = " /posts/$postId " params = { { postId : '123' } }

Post 123 </ Link

// With search params < Link to = " /posts " search = { { page : 2 , filter : 'react' } }

Page 2 </ Link

// Active link styling < Link to = " /posts " activeProps = { { className : 'active' } } inactiveProps = { { className : 'inactive' } } activeOptions = { { exact : true } }

Posts </ Link

// Preloading < Link to = " /posts " preload = " intent "

Posts </ Link

< Link to = " /dashboard " preload = " viewport "

Dashboard </ Link

// Hash < Link to = " /docs " hash = " api-reference "

API Reference </ Link

Programmatic Navigation import { useNavigate , useRouter } from '@tanstack/react-router' function MyComponent ( ) { const navigate = useNavigate ( ) const router = useRouter ( ) // Navigate to a route navigate ( { to : '/posts' , search : { page : 1 } } ) // Navigate with replace navigate ( { to : '/posts' , replace : true } ) // Relative navigation navigate ( { to : '.' , search : ( prev ) => ( { ... prev , page : 2 } ) } ) // Go back/forward router . history . back ( ) router . history . forward ( ) // Invalidate and reload current route router . invalidate ( ) } Redirects import { redirect } from '@tanstack/react-router' // In beforeLoad or loader throw redirect ( { to : '/login' , search : { redirect : location . href } , // Optional status code statusCode : 301 , // Permanent redirect (SSR) } ) Navigation Blocking import { useBlocker } from '@tanstack/react-router' function FormComponent ( ) { const [ isDirty , setIsDirty ] = useState ( false ) useBlocker ( { shouldBlockFn : ( ) => isDirty , withResolver : true , // Shows confirm dialog } ) // Or with custom UI const { proceed , reset , status } = useBlocker ( { shouldBlockFn : ( ) => isDirty , } ) if ( status === 'blocked' ) { return ( < div

< p

Are you sure you want to leave? </ p

< button onClick = { proceed }

Leave </ button

< button onClick = { reset }

Stay </ button

</ div

) } } Code Splitting Automatic (File-Based Routing) With file-based routing, create a lazy file: routes/ posts.tsx # Critical: loader, beforeLoad, meta posts.lazy.tsx # Lazy: component, pendingComponent, errorComponent // posts.tsx (loaded eagerly) export const Route = createFileRoute ( '/posts' ) ( { loader : ( ) => fetchPosts ( ) , } ) // posts.lazy.tsx (loaded lazily) import { createLazyFileRoute } from '@tanstack/react-router' export const Route = createLazyFileRoute ( '/posts' ) ( { component : PostsComponent , pendingComponent : PostsLoading , errorComponent : PostsError , } ) Manual Code Splitting const postsRoute = createRoute ( { getParentRoute : ( ) => rootRoute , path : '/posts' , loader : ( ) => fetchPosts ( ) , } ) . lazy ( ( ) => import ( './posts.lazy' ) . then ( ( d ) => d . Route ) ) Preloading // Router-level defaults const router = createRouter ( { routeTree , defaultPreload : 'intent' , // 'intent' | 'viewport' | 'render' | false defaultPreloadStaleTime : 30_000 , // 30 seconds } ) // Route-level export const Route = createFileRoute ( '/posts/$postId' ) ( { // Stale time for the loader data staleTime : 5_000 , // How long preloaded data stays fresh preloadStaleTime : 30_000 , } ) // Link-level < Link to = " /posts " preload = " intent " preloadDelay = { 100 }

Posts </ Link

Type Safety Register Router Type // Declare module for type inference declare module '@tanstack/react-router' { interface Register { router : typeof router } } Type-Safe Hooks All hooks are fully typed based on the route tree: // useParams - typed to route's params const { postId } = useParams ( { from : '/posts/$postId' } ) // useSearch - typed to route's search schema const { page } = useSearch ( { from : '/posts' } ) // useLoaderData - typed to loader return const data = useLoaderData ( { from : '/posts/$postId' } ) // useRouteContext - typed to route context const { auth } = useRouteContext ( { from : '/protected' } ) Route Generics import { createFileRoute } from '@tanstack/react-router' export const Route = createFileRoute ( '/posts/$postId' ) ( { // TypeScript infers: // params: { postId: string } // search: validated search schema type // loaderData: return type of loader // context: router context type } ) Authenticated Routes // __root.tsx export const Route = createRootRouteWithContext < { auth : AuthContext }

( ) ( { component : RootComponent , } ) // _authenticated.tsx (pathless layout for auth) export const Route = createFileRoute ( '/_authenticated' ) ( { beforeLoad : ( { context , location } ) => { if ( ! context . auth . isAuthenticated ) { throw redirect ( { to : '/login' , search : { redirect : location . href } , } ) } } , } ) // _authenticated/dashboard.tsx export const Route = createFileRoute ( '/_authenticated/dashboard' ) ( { component : Dashboard , // Only accessible when authenticated } ) Scroll Restoration const router = createRouter ( { routeTree , // Enable scroll restoration defaultScrollRestoration : true , } ) // Or per-route export const Route = createFileRoute ( '/posts' ) ( { // Scroll to top on navigation scrollRestoration : true , } ) // Custom scroll restoration key < ScrollRestoration getKey = { ( location ) => location . pathname } /> Route Masking Display a different URL than the actual route: < Link to = " /photos/$photoId " params = { { photoId : photo . id } } mask = { { to : '/photos' , search : { photoId : photo . id } } }

View Photo </ Link

// Or programmatically navigate ( { to : '/photos/$photoId' , params : { photoId : photo . id } , mask : { to : '/photos' , search : { photoId : photo . id } } , } ) Not Found Handling // Global 404 const router = createRouter ( { routeTree , defaultNotFoundComponent : ( ) => < div

Page not found </ div

, } ) // Route-level 404 export const Route = createFileRoute ( '/posts/$postId' ) ( { loader : async ( { params } ) => { const post = await fetchPost ( params . postId ) if ( ! post ) throw notFound ( ) return post } , notFoundComponent : ( ) => < div

Post not found </ div

, } ) Head Management export const Route = createFileRoute ( '/posts/$postId' ) ( { head : ( { loaderData } ) => ( { meta : [ { title : loaderData . title } , { name : 'description' , content : loaderData . excerpt } , { property : 'og:title' , content : loaderData . title } , ] , links : [ { rel : 'canonical' , href : https://example.com/posts/ ${ loaderData . id } } , ] , } ) , } ) Integration with TanStack Query import { queryOptions } from '@tanstack/react-query' const postsQueryOptions = queryOptions ( { queryKey : [ 'posts' ] , queryFn : fetchPosts , } ) export const Route = createFileRoute ( '/posts' ) ( { loader : ( { context : { queryClient } } ) => { // Ensure data is in cache, won't refetch if fresh return queryClient . ensureQueryData ( postsQueryOptions ) } , component : PostsComponent , } ) function PostsComponent ( ) { // Use the same query options for reactive updates const { data : posts } = useSuspenseQuery ( postsQueryOptions ) return < PostsList posts = { posts } /> } Router Hooks Reference Hook Purpose useRouter() Access router instance useRouterState() Subscribe to router state useParams() Get route path params useSearch() Get validated search params useLoaderData() Get route loader data useRouteContext() Get route context useNavigate() Get navigate function useLocation() Get current location useMatches() Get all matched routes useMatch() Get specific route match useBlocker() Block navigation useLinkProps() Get link props for custom components useMatchRoute() Check if a route matches Best Practices Use file-based routing for most applications - it's simpler and auto-generates the route tree Validate search params with Zod or custom validators for type safety Use loaderDeps to control when loaders re-execute based on search param changes Leverage context for dependency injection (QueryClient, auth state) Use beforeLoad for authentication guards, not in components Separate critical vs lazy code - keep loaders in the main file, components in .lazy.tsx Use preload="intent" on Links for perceived performance Use staleTime to prevent unnecessary refetches during navigation Register the router type for full TypeScript inference across the app Use notFound() instead of conditional rendering for 404 states Colocate search param logic with routes that own them Use pathless layouts ( _authenticated ) for shared auth/layout logic without URL segments Common Pitfalls Forgetting to register the router type ( declare module ) Not using loaderDeps when loader depends on search params (causes stale data) Putting auth checks in components instead of beforeLoad (flash of protected content) Not handling the loading state with pendingComponent Using useEffect for data fetching instead of route loaders Mutating search params directly instead of using navigate/Link Not wrapping the app with RouterProvider Forgetting getParentRoute in code-based route definitions