React Router (@tanstack/react-router)

This skill builds on router-core. Read @tanstack/router-core#router-core first for foundational concepts.

CRITICAL: TanStack Router types are FULLY INFERRED. Never cast, never annotate inferred values. CRITICAL: TanStack Router is CLIENT-FIRST. Loaders run on the client by default, not on the server. CRITICAL: Do not confuse @tanstack/react-router with react-router-dom/react-router. They are completely different libraries with different APIs.

Full Setup: File-Based Routing with Vite

1. Install Dependencies

shell

npm install @tanstack/react-router
npm install -D @tanstack/router-plugin @tanstack/react-router-devtools

2. Configure Vite Plugin

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    // MUST come before react()
    tanstackRouter({
      target: 'react',
      autoCodeSplitting: true,
    }),
    react(),
  ],
})

3. Create Root Route

tsx

// src/routes/__root.tsx
import { createRootRoute, Link, Outlet } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

export const Route = createRootRoute({
  component: RootLayout,
})

function RootLayout() {
  return (
    <>
      <nav>
        <Link to="/" className="[&.active]:font-bold">
          Home
        </Link>
        <Link to="/about" className="[&.active]:font-bold">
          About
        </Link>
      </nav>
      <hr />
      <Outlet />
      <TanStackRouterDevtools />
    </>
  )
}

4. Create Route Files

tsx

// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: HomePage,
})

function HomePage() {
  return <h1>Welcome Home</h1>
}

tsx

// src/routes/about.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/about')({
  component: AboutPage,
})

function AboutPage() {
  return <h1>About</h1>
}

5. Create Router Instance and Register Types

tsx

// src/main.tsx
import { StrictMode } from 'react'
import ReactDOM from 'react-dom/client'
import { RouterProvider, createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({ routeTree })

// REQUIRED — without this, Link/useNavigate/useSearch have no type safety
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

const rootElement = document.getElementById('root')!
if (!rootElement.innerHTML) {
  const root = ReactDOM.createRoot(rootElement)
  root.render(
    <StrictMode>
      <RouterProvider router={router} />
    </StrictMode>,
  )
}

Hooks Reference

All hooks are imported from @tanstack/react-router.

useRouter()

Access the router instance directly:

tsx

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

function InvalidateButton() {
  const router = useRouter()
  return <button onClick={() => router.invalidate()}>Refresh data</button>
}

useRouterState()

Subscribe to router state changes. Exposes the entire state and thus incurs a performance cost. For matches or location favor useMatches and useLocation.

tsx

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

function LoadingIndicator() {
  const isLoading = useRouterState({ select: (s) => s.isLoading })
  return isLoading ? <div>Loading...</div> : null
}

useNavigate()

Programmatic navigation (prefer <Link> for user-clickable elements):

tsx

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

function AfterSubmit() {
  const navigate = useNavigate()

  const handleSubmit = async () => {
    await saveData()
    navigate({ to: '/posts/$postId', params: { postId: '123' } })
  }

  return <button onClick={handleSubmit}>Save</button>
}

useSearch({ from })

Read validated search params:

tsx

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

function Pagination() {
  const { page } = useSearch({ from: '/products' })
  return <span>Page {page}</span>
}

useParams({ from })

Read path params:

tsx

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

function PostHeader() {
  const { postId } = useParams({ from: '/posts/$postId' })
  return <h2>Post {postId}</h2>
}

useLoaderData({ from })

Read data returned from the route loader:

tsx

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

function PostContent() {
  const { post } = useLoaderData({ from: '/posts/$postId' })
  return <article>{post.content}</article>
}

useMatch({ from })

Access the full route match (params, search, loader data, context):

tsx

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

function PostDetails() {
  const match = useMatch({ from: '/posts/$postId' })
  return <div>{match.loaderData.post.title}</div>
}

Other Hooks

All imported from @tanstack/react-router:

useMatches() — array of all active route matches (useful for breadcrumbs)
useRouteContext({ from }) — read context from beforeLoad or parent routes
useBlocker({ shouldBlockFn }) — block navigation for unsaved changes
useCanGoBack() — returns boolean, check if history has entries to go back to
useLocation() — current parsed location (pathname, search, hash)
useLinkProps({ to, params?, search? }) — get <a> props for custom link elements
useMatchRoute() — returns a function: matchRoute({ to }) => match | false

Components Reference

RouterProvider

Mount the router at the top of your React tree:

tsx

<RouterProvider router={router} />

Link

Type-safe navigation link with <a> semantics:

tsx

<Link to="/posts/$postId" params={{ postId: '42' }}>
  View Post
</Link>

Outlet

Renders the matched child route component:

tsx

function Layout() {
  return (
    <div>
      <Sidebar />
      <main>
        <Outlet />
      </main>
    </div>
  )
}

Navigate

Declarative redirect component:

tsx

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

function OldPage() {
  return <Navigate to="/new-page" />
}

Await

Renders deferred data from unawaited loader promises with Suspense:

tsx

import { Await } from '@tanstack/react-router'
import { Suspense } from 'react'

function PostWithComments() {
  const { deferredComments } = Route.useLoaderData()
  return (
    <div>
      <h1>Post</h1>
      <Suspense fallback={<div>Loading comments...</div>}>
        <Await promise={deferredComments}>
          {(comments) => (
            <ul>
              {comments.map((c) => (
                <li key={c.id}>{c.text}</li>
              ))}
            </ul>
          )}
        </Await>
      </Suspense>
    </div>
  )
}

CatchBoundary

Error boundary for component-level error handling (route-level errors use errorComponent route option):

tsx

import { CatchBoundary } from '@tanstack/react-router'
;<CatchBoundary
  getResetKey={() => 'widget'}
  onCatch={(error) => console.error(error)}
  errorComponent={({ error }) => <div>{String(error)}</div>}
>
  <RiskyWidget />
</CatchBoundary>

React-Specific Patterns

Custom Link Component with createLink

Wrap Link in a custom component while preserving type safety:

tsx

import { createLink } from '@tanstack/react-router'
import { forwardRef, type ComponentPropsWithoutRef } from 'react'

const StyledLinkComponent = forwardRef<
  HTMLAnchorElement,
  ComponentPropsWithoutRef<'a'>
>((props, ref) => (
  <a ref={ref} {...props} className={`styled-link ${props.className ?? ''}`} />
))

const StyledLink = createLink(StyledLinkComponent)

// Usage — same type-safe props as Link
function Nav() {
  return (
    <StyledLink to="/posts/$postId" params={{ postId: '42' }}>
      Post
    </StyledLink>
  )
}

Reusable Components with Router Hooks

To create a component that uses router hooks across multiple routes, pass a union of route paths as the from prop:

tsx

function PostIdDisplay({ from }: { from: '/posts/$id' | '/drafts/$id' }) {
  const { id } = useParams({ from })
  return <span>ID: {id}</span>
}

// Usage in different route components
<PostIdDisplay from="/posts/$id" />
<PostIdDisplay from="/drafts/$id" />

This pattern avoids strict: false (which returns an imprecise union) while keeping the component reusable across specific known routes.

Auth Provider Must Wrap RouterProvider

If routes use auth context (via createRootRouteWithContext), the auth provider must be an ancestor of RouterProvider:

tsx

// CORRECT — AuthProvider wraps RouterProvider
function App() {
  return (
    <AuthProvider>
      <RouterProvider router={router} />
    </AuthProvider>
  )
}

// WRONG — RouterProvider outside auth provider
function App() {
  return (
    <RouterProvider router={router}>
      <AuthProvider>{/* ... */}</AuthProvider>
    </RouterProvider>
  )
}

Or use the Wrap router option to provide context without wrapping externally:

tsx

const router = createRouter({
  routeTree,
  Wrap: ({ children }) => (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  ),
})

Common Mistakes

1. HIGH: Using React hooks in beforeLoad or loader

beforeLoad and loader are NOT React components — they are plain async functions. React hooks cannot be called in them. Pass auth state via router context instead.

tsx

// WRONG — useAuth is a React hook, cannot be called here
beforeLoad: () => {
  const auth = useAuth()
  if (!auth.user) throw redirect({ to: '/login' })
}

// CORRECT — read auth from router context
beforeLoad: ({ context }) => {
  if (!context.auth.isAuthenticated) {
    throw redirect({ to: '/login' })
  }
}

2. HIGH: Wrapping RouterProvider inside an auth provider incorrectly

Create the router once with an undefined! placeholder, then inject live auth via RouterProvider's context prop. Do NOT recreate the router on auth changes — this resets caches and rebuilds the tree.

tsx

// CORRECT — create router once, inject live auth via context prop
const router = createRouter({
  routeTree,
  context: { auth: undefined! }, // placeholder, filled by RouterProvider
})

function InnerApp() {
  const auth = useAuth()
  return <RouterProvider router={router} context={{ auth }} />
}

function App() {
  return (
    <AuthProvider>
      <InnerApp />
    </AuthProvider>
  )
}

3. MEDIUM: Missing Suspense boundary for Await/deferred data

Await requires a <Suspense> ancestor. Without it, the deferred promise has no fallback UI and throws.

tsx

// WRONG — no Suspense boundary
<Await promise={deferredData}>{(data) => <div>{data}</div>}</Await>

// CORRECT — wrap in Suspense
<Suspense fallback={<div>Loading...</div>}>
  <Await promise={deferredData}>{(data) => <div>{data}</div>}</Await>
</Suspense>

Cross-References

@tanstack/router-core#router-core — all sub-skills for domain-specific patterns (search params, data loading, navigation, auth, SSR, etc.)

@tanstack/react-router

react-router

React Router (@tanstack/react-router)#

Full Setup: File-Based Routing with Vite#

1. Install Dependencies#

2. Configure Vite Plugin#

3. Create Root Route#

4. Create Route Files#

5. Create Router Instance and Register Types#

Hooks Reference#

useRouter()#

useRouterState()#

useNavigate()#

useSearch({ from })#

useParams({ from })#

useLoaderData({ from })#

useMatch({ from })#

Other Hooks#

Components Reference#

RouterProvider#

Link#

Outlet#

Navigate#

Await#

CatchBoundary#

React-Specific Patterns#

Custom Link Component with createLink#

Reusable Components with Router Hooks#

Auth Provider Must Wrap RouterProvider#

Common Mistakes#

1. HIGH: Using React hooks in beforeLoad or loader#

2. HIGH: Wrapping RouterProvider inside an auth provider incorrectly#

3. MEDIUM: Missing Suspense boundary for Await/deferred data#

Cross-References#