react-router

React Router (

@tanstack/react-router

)

This skill builds on router-core. Read router-core first for foundational concepts.

This skill covers the React-specific bindings, components, hooks, and setup for TanStack Router.

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

bash

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>Error: {error.message}</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

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

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

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

react-router

NPX Install

Tags

SKILL.md Content

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

react-router

NPX Install

Tags

SKILL.md Content

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

React Router (
`@tanstack/react-router`
)

`useRouter()`

`useRouterState()`

`useNavigate()`

`useSearch({ from })`

`useParams({ from })`

`useLoaderData({ from })`

`useMatch({ from })`

`RouterProvider`

`Link`

`Outlet`

`Navigate`

`Await`

`CatchBoundary`

Custom Link Component with
`createLink`

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

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