React Router User Guide

React Router is the standard routing library for React applications. It supports three distinct usage modes — declarative routing, data routers, and full-stack framework mode — giving you the flexibility to use it as a simple client-side router or a complete application framework with server-side rendering, data loading, and mutations.

This guide covers everything you need to install, configure, and use React Router effectively in any of its modes.

1. Quick Start

1.1 Create a New Project (Framework Mode)

The fastest way to start a new React Router project is with the scaffolding CLI:

npx create-react-router@latest my-app
cd my-app
npm install
npm run dev

This creates a full-stack project with file-based routing, SSR, and the Vite dev server. Open http://localhost:5173 to see your app.

1.2 Add to an Existing React App (Library Mode)

If you already have a React app and want to add routing:

npm install react-router

Then wrap your app with a router:

import { BrowserRouter, Routes, Route, Link } from "react-router";

function App() {
  return (
    <BrowserRouter>
      <nav>
        <Link to="/">Home</Link>
        <Link to="/about">About</Link>
      </nav>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
      </Routes>
    </BrowserRouter>
  );
}

function Home() {
  return <h1>Home</h1>;
}

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

1.3 Data Router (Library Mode with Data APIs)

For apps that need loaders, actions, and data-driven navigation:

import {
  createBrowserRouter,
  RouterProvider,
  Link,
  useLoaderData,
  Outlet,
} from "react-router";

const router = createBrowserRouter([
  {
    path: "/",
    element: <Root />,
    children: [
      {
        index: true,
        element: <Home />,
        loader: async () => {
          const res = await fetch("/api/dashboard");
          return res.json();
        },
      },
    ],
  },
]);

function Root() {
  return (
    <div>
      <nav>
        <Link to="/">Home</Link>
      </nav>
      <Outlet />
    </div>
  );
}

function Home() {
  const data = useLoaderData();
  return <h1>Welcome, {data.user.name}</h1>;
}

function App() {
  return <RouterProvider router={router} />;
}

Tip

If you are starting a new project today, framework mode gives you the most capabilities out of the box — SSR, code splitting, type-safe routing, and data APIs all pre-configured. Use library mode when integrating into an existing app or when you need full control over your build pipeline.

2. Installation

2.1 System Requirements

2.2 Library Mode Installation

Install the core package:

# npm
npm install react-router

# pnpm
pnpm add react-router

# yarn
yarn add react-router

# bun
bun add react-router

Important

The react-router-dom package still exists but is a thin re-export shim. Import everything directly from react-router. The DOM-specific exports (like RouterProvider for the browser) are available from react-router/dom when needed.

2.3 Framework Mode Installation

Framework mode requires the Vite plugin and a server adapter:

# Core + framework
npm install react-router @react-router/dev

# Pick a server adapter (choose one)
npm install @react-router/serve       # Built-in production server
npm install @react-router/express     # Express adapter
npm install @react-router/node        # Node.js streams adapter
npm install @react-router/cloudflare  # Cloudflare Workers/Pages
npm install @react-router/architect   # AWS Architect

2.4 Vite Configuration (Framework Mode)

Framework mode uses Vite as its build tool. Create or update vite.config.ts:

import { reactRouter } from "@react-router/dev/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [reactRouter()],
});

React Router supports Vite v5, v6, v7-beta, and v8.

2.5 TypeScript Setup

React Router ships with full TypeScript support. For framework mode, the route typegen automatically generates types for your routes:

# Generate route types (framework mode)
npx react-router typegen

Add the generated types to your tsconfig.json:

{
  "compilerOptions": {
    "types": [".react-router/types"]
  }
}

2.6 Package Overview

3. Configuration

3.1 Framework Mode Configuration (react-router.config.ts)

Framework mode is configured via react-router.config.ts at the project root:

import type { Config } from "@react-router/dev/config";

export default {
  // App source directory (default: "app")
  appDirectory: "app",

  // URL basename (default: "/")
  basename: "/",

  // Build output directory (default: "build")
  buildDirectory: "build",

  // Server build filename (default: "index.js")
  serverBuildFile: "index.js",

  // Module format: "esm" or "cjs" (default: "esm")
  serverModuleFormat: "esm",

  // Enable SSR (default: true, set false for SPA mode)
  ssr: true,
} satisfies Config;

3.2 SPA Mode

Disable server-side rendering to build a single-page application:

import type { Config } from "@react-router/dev/config";

export default {
  ssr: false,
} satisfies Config;

In SPA mode, the build produces a static index.html and client-side JavaScript. No server runtime is required — you can deploy to any static hosting.

3.3 Prerendering

Generate static HTML at build time for specific routes:

import type { Config } from "@react-router/dev/config";

export default {
  // Prerender all routes
  prerender: true,

  // Or prerender specific URLs
  prerender: ["/", "/about", "/blog/intro"],

  // Or compute URLs dynamically
  prerender: async () => {
    const posts = await fetchBlogSlugs();
    return ["/", "/about", ...posts.map((p) => `/blog/${p.slug}`)];
  },
} satisfies Config;

Note

Prerendering is compatible with SSR. Non-prerendered routes will still use server rendering at request time. This is useful for sites where some pages are static (landing, blog) and others are dynamic (dashboard, settings).

3.4 Lazy Route Discovery

React Router can lazily discover routes to reduce initial bundle size:

import type { Config } from "@react-router/dev/config";

export default {
  routeDiscovery: {
    // "lazy" = discover routes as user navigates (default)
    // "initial" = send all routes in the initial response
    mode: "lazy",
  },
} satisfies Config;

In lazy mode, the manifest for unvisited routes is fetched on demand when the user hovers or focuses a link pointing to an undiscovered route.

3.5 Server Bundles

Split your server code into multiple bundles for different deployment targets:

import type { Config } from "@react-router/dev/config";

export default {
  serverBundles({ branch }) {
    // Split into separate bundles based on route tree
    if (branch.some((route) => route.id.startsWith("routes/api"))) {
      return "api";
    }
    return "pages";
  },
} satisfies Config;

3.6 CSRF Protection

Restrict which origins can submit form data to your actions:

import type { Config } from "@react-router/dev/config";

export default {
  allowedActionOrigins: ["https://myapp.com", "https://admin.myapp.com"],
} satisfies Config;

3.7 Future Flags

Opt into upcoming breaking changes early:

import type { Config } from "@react-router/dev/config";

export default {
  future: {
    v8_middleware: true,           // Enable middleware support
    v8_splitRouteModules: true,    // Split route modules for better code splitting
    v8_viteEnvironmentApi: true,   // Use Vite environment API
    unstable_optimizeDeps: true,   // Pre-bundle dependencies
    unstable_passThroughRequests: true,  // Pass non-matched requests through
    unstable_subResourceIntegrity: true, // SRI for scripts/styles
    unstable_trailingSlashAwareDataRequests: true, // Trailing slash handling
  },
} satisfies Config;

3.8 Route Configuration (routes.ts)

In framework mode, define your routes in app/routes.ts:

import { route, index, layout, prefix } from "@react-router/dev/routes";

export default [
  // Index route at "/"
  index("routes/home.tsx"),

  // Regular route at "/about"
  route("about", "routes/about.tsx"),

  // Nested routes under "/dashboard"
  route("dashboard", "routes/dashboard/layout.tsx", [
    index("routes/dashboard/index.tsx"),
    route("settings", "routes/dashboard/settings.tsx"),
    route("profile", "routes/dashboard/profile.tsx"),
  ]),

  // Layout route (no URL segment, wraps children)
  layout("routes/auth-layout.tsx", [
    route("login", "routes/login.tsx"),
    route("register", "routes/register.tsx"),
  ]),

  // API routes with a prefix
  ...prefix("api", [
    route("users", "routes/api/users.tsx"),
    route("posts", "routes/api/posts.tsx"),
  ]),
];

Route Configuration API Reference

3.9 File-System Routing

Instead of manual route configuration, use the filesystem convention:

npm install @react-router/fs-routes

// app/routes.ts
import { flatRoutes } from "@react-router/fs-routes";

export default flatRoutes();

The filesystem convention uses the app/routes/ directory:

Key conventions:

• $param — dynamic URL segment
• ($param) — optional dynamic segment
• [literal] — escaped literal (for dots, brackets)
• _index — index route
• _ prefix — pathless layout (no URL segment)
• . — path separator (replaces /)
• Supported extensions: .js, .jsx, .ts, .tsx, .md, .mdx

3.10 Library Mode Configuration

Library mode (declarative or data router) requires no configuration file. You configure routing entirely in code. For the BrowserRouter, the basename prop serves the same purpose as the framework config option:

<BrowserRouter basename="/app">
  <Routes>
    <Route path="/" element={<Home />} />
  </Routes>
</BrowserRouter>

3.11 Post-Build Hook

Run custom logic after the build completes:

import type { Config } from "@react-router/dev/config";

export default {
  async buildEnd({ buildManifest, reactRouterConfig, viteConfig }) {
    // Generate a sitemap, copy assets, notify a service, etc.
    await generateSitemap(buildManifest);
  },
} satisfies Config;

3.12 Plugin Presets

Extend configuration with reusable presets:

import type { Config } from "@react-router/dev/config";
import vercel from "@vercel/react-router/preset";

export default {
  presets: [vercel()],
} satisfies Config;

Presets can provide default configuration values, routes, and server adapters that are merged with your own config.

4. Core Usage

4.1 Understanding the Three Modes

React Router offers three progressively richer usage modes:

Each mode builds on the previous one. Declarative mode provides components and hooks for URL-based rendering. Data Router mode adds loaders, actions, and pending states. Framework mode adds SSR, code splitting, and the build pipeline.

4.2 Declarative Routing

Basic Setup

import { BrowserRouter, Routes, Route, Link } from "react-router";

function App() {
  return (
    <BrowserRouter>
      <nav>
        <Link to="/">Home</Link>
        <Link to="/products">Products</Link>
        <Link to="/about">About</Link>
      </nav>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/products" element={<Products />} />
        <Route path="/products/:id" element={<ProductDetail />} />
        <Route path="/about" element={<About />} />
        <Route path="*" element={<NotFound />} />
      </Routes>
    </BrowserRouter>
  );
}

Nested Routes

Nested routes allow you to compose layouts with child content areas. Parent routes render an <Outlet /> where child routes appear:

import { BrowserRouter, Routes, Route, Link, Outlet } from "react-router";

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Layout />}>
          <Route index element={<Home />} />
          <Route path="dashboard" element={<Dashboard />}>
            <Route index element={<DashboardHome />} />
            <Route path="settings" element={<Settings />} />
            <Route path="profile" element={<Profile />} />
          </Route>
          <Route path="*" element={<NotFound />} />
        </Route>
      </Routes>
    </BrowserRouter>
  );
}

function Layout() {
  return (
    <div>
      <header>My App</header>
      {/* Child routes render here */}
      <Outlet />
      <footer>&copy; 2026</footer>
    </div>
  );
}

function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      <nav>
        <Link to="">Overview</Link>
        <Link to="settings">Settings</Link>
        <Link to="profile">Profile</Link>
      </nav>
      <Outlet />
    </div>
  );
}

When the URL is /dashboard/settings, the render hierarchy is: Layout > Dashboard > Settings, with each parent rendering its <Outlet /> where the child appears.

Index Routes

An index route renders when the parent route matches exactly (no further path segments):

<Route path="dashboard" element={<Dashboard />}>
  {/* Renders at /dashboard (exact) */}
  <Route index element={<DashboardHome />} />
  {/* Renders at /dashboard/settings */}
  <Route path="settings" element={<Settings />} />
</Route>

Router Types

// Hash-based routing (URLs like /#/about)
import { HashRouter, Routes, Route } from "react-router";

<HashRouter>
  <Routes>
    <Route path="/" element={<Home />} />
  </Routes>
</HashRouter>

// Memory routing (for tests)
import { MemoryRouter } from "react-router";

<MemoryRouter initialEntries={["/dashboard"]}>
  <Routes>
    <Route path="/dashboard" element={<Dashboard />} />
  </Routes>
</MemoryRouter>

// Static routing (SSR)
import { StaticRouter } from "react-router";

function handleRequest(req) {
  const html = renderToString(
    <StaticRouter location={req.url}>
      <App />
    </StaticRouter>
  );
  return html;
}

4.3 Data Router Mode

Data routers unlock loaders, actions, fetchers, and pending UI — the full data layer.

Creating a Data Router

import {
  createBrowserRouter,
  RouterProvider,
  Outlet,
  Link,
  useLoaderData,
  useNavigation,
} from "react-router";

const router = createBrowserRouter([
  {
    path: "/",
    element: <Root />,
    errorElement: <ErrorBoundary />,
    children: [
      {
        index: true,
        element: <Home />,
        loader: homeLoader,
      },
      {
        path: "contacts/:contactId",
        element: <Contact />,
        loader: contactLoader,
        action: contactAction,
      },
    ],
  },
]);

function App() {
  return <RouterProvider router={router} />;
}

Note

createBrowserRouter is for browser environments. For hash-based routing use createHashRouter, and for testing use createMemoryRouter. The API is identical across all three; only the history implementation differs.

Router Factory Functions

Loaders

Loaders fetch data before a route renders. They run on every navigation to that route:

// Define the loader
async function contactLoader({ params, request }) {
  const response = await fetch(`/api/contacts/${params.contactId}`);
  if (!response.ok) {
    throw new Response("Contact not found", { status: 404 });
  }
  return response.json();
}

// Use the data in the component
function Contact() {
  const contact = useLoaderData();
  return (
    <div>
      <h1>{contact.name}</h1>
      <p>{contact.email}</p>
    </div>
  );
}

// Wire them together in the route
{
  path: "contacts/:contactId",
  element: <Contact />,
  loader: contactLoader,
}

Loaders receive two arguments:

Actions

Actions handle data mutations (form submissions, API calls that change state):

async function contactAction({ request, params }) {
  const formData = await request.formData();
  const updates = Object.fromEntries(formData);

  const response = await fetch(`/api/contacts/${params.contactId}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(updates),
  });

  if (!response.ok) {
    return { error: "Failed to update contact" };
  }

  // Returning a redirect navigates after the action completes
  return redirect(`/contacts/${params.contactId}`);
}

function EditContact() {
  const contact = useLoaderData();
  const actionData = useActionData();

  return (
    <Form method="post">
      {actionData?.error && <p className="error">{actionData.error}</p>}
      <input name="name" defaultValue={contact.name} />
      <input name="email" defaultValue={contact.email} />
      <button type="submit">Save</button>
    </Form>
  );
}

After an action completes, React Router automatically revalidates all active loaders so the UI stays in sync with the server.

Error Boundaries

import { useRouteError, isRouteErrorResponse } from "react-router";

function ErrorBoundary() {
  const error = useRouteError();

  if (isRouteErrorResponse(error)) {
    return (
      <div>
        <h1>{error.status} {error.statusText}</h1>
        <p>{error.data}</p>
      </div>
    );
  }

  return (
    <div>
      <h1>Something went wrong</h1>
      <p>{error instanceof Error ? error.message : "Unknown error"}</p>
    </div>
  );
}

// Attach to a route
const router = createBrowserRouter([
  {
    path: "/",
    element: <Root />,
    errorElement: <ErrorBoundary />,
    children: [
      {
        path: "invoices/:id",
        element: <Invoice />,
        loader: invoiceLoader,
        // This error boundary catches errors specific to this route
        errorElement: <InvoiceError />,
      },
    ],
  },
]);

Error boundaries bubble up: if a child route throws and has no errorElement, the parent's error boundary catches it. This lets you set a single root error boundary as a fallback and add granular error handling only where needed.

4.4 Framework Mode

Framework mode provides the richest experience: file-based routing, SSR, automatic code splitting, type-safe routes, and integrated data loading.

Project Structure

my-app/
├── app/
│   ├── root.tsx          # Root layout (HTML shell)
│   ├── routes.ts         # Route definitions
│   └── routes/
│       ├── _index.tsx    # Home page (/)
│       ├── about.tsx     # /about
│       └── blog.$slug.tsx # /blog/:slug
├── react-router.config.ts
├── vite.config.ts
└── package.json

Root Layout (app/root.tsx)

The root layout defines the HTML shell for your application:

import {
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
} from "react-router";

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

export default function Root() {
  return <Outlet />;
}

The SSR components in the root layout serve specific roles:

Route Modules

Each route file can export several conventions:

// app/routes/blog.$slug.tsx
import type { Route } from "./+types/blog.$slug";

// Metadata for <head>
export const meta: Route.MetaFunction = ({ data }) => {
  return [
    { title: data.post.title },
    { name: "description", content: data.post.excerpt },
  ];
};

// Link tags for <head>
export const links: Route.LinksFunction = () => {
  return [{ rel: "stylesheet", href: "/blog.css" }];
};

// HTTP response headers
export const headers: Route.HeadersFunction = () => {
  return {
    "Cache-Control": "public, max-age=3600",
  };
};

// Server-side data loading
export async function loader({ params }: Route.LoaderArgs) {
  const post = await db.posts.findBySlug(params.slug);
  if (!post) throw new Response("Not found", { status: 404 });
  return { post };
}

// Server-side mutation handling
export async function action({ request, params }: Route.ActionArgs) {
  const formData = await request.formData();
  await db.comments.create({
    postSlug: params.slug,
    body: formData.get("body") as string,
  });
  return { ok: true };
}

// Default export = the page component
export default function BlogPost({ loaderData }: Route.ComponentProps) {
  const { post } = loaderData;
  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.html }} />
    </article>
  );
}

// Error boundary for this route
export function ErrorBoundary() {
  const error = useRouteError();
  return <div>Error loading post</div>;
}

Route Module Exports Summary

Client Loaders and Actions

Run loaders and actions on the client side (in addition to or instead of server):

// Client-side loader (runs in the browser)
export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) {
  // Check cache first
  const cached = sessionStorage.getItem("dashboard-data");
  if (cached) return JSON.parse(cached);

  // Fall back to server loader
  const data = await serverLoader();
  sessionStorage.setItem("dashboard-data", JSON.stringify(data));
  return data;
}

// Tell React Router this route needs the client loader to hydrate
clientLoader.hydrate = true;

// Client-side action
export async function clientAction({
  request,
  serverAction,
}: Route.ClientActionArgs) {
  const formData = await request.formData();

  // Client-side validation
  if (!formData.get("email")) {
    return { error: "Email is required" };
  }

  // Forward to server
  return serverAction();
}

Tip

Client loaders are powerful for caching strategies. Use them to implement stale-while-revalidate patterns, read from IndexedDB or localStorage, or skip the server entirely for data that only exists on the client.

4.5 Navigation Components

Link

The basic navigation component. Renders an <a> tag that performs client-side navigation:

import { Link } from "react-router";

// Basic link
<Link to="/about">About</Link>

// Relative link (relative to current route)
<Link to="settings">Settings</Link>

// Link with state (accessible via useLocation().state)
<Link to="/login" state={{ from: "/dashboard" }}>Login</Link>

// Replace history entry (no back button)
<Link to="/welcome" replace>Welcome</Link>

// Prevent scroll reset on navigation
<Link to="/tab2" preventScrollReset>Tab 2</Link>

// Link with view transition animation
<Link to="/next" viewTransition>Next Page</Link>

// Relative to path (not route hierarchy)
<Link to=".." relative="path">Back</Link>

NavLink

An enhanced Link that knows whether it is active, pending, or transitioning:

import { NavLink } from "react-router";

// className as function
<NavLink
  to="/dashboard"
  className={({ isActive, isPending, isTransitioning }) =>
    [
      isPending ? "pending" : "",
      isActive ? "active" : "",
      isTransitioning ? "transitioning" : "",
    ].join(" ")
  }
>
  Dashboard
</NavLink>

// style as function
<NavLink
  to="/messages"
  style={({ isActive }) => ({
    fontWeight: isActive ? "bold" : "normal",
    color: isActive ? "#1a73e8" : "inherit",
  })}
>
  Messages
</NavLink>

// Children as render function
<NavLink to="/tasks">
  {({ isActive }) => (
    <span>{isActive ? ">> Tasks" : "Tasks"}</span>
  )}
</NavLink>

// End prop — only match exact path, not descendant routes
<NavLink to="/dashboard" end>Dashboard Home</NavLink>

The end prop is important for parent routes. Without it, <NavLink to="/dashboard"> would be active on /dashboard/settings too. With end, it is only active on exactly /dashboard.

Form

The Form component provides declarative data mutations. It works like a standard HTML <form> but intercepts the submission to perform client-side navigation and trigger route actions:

import { Form } from "react-router";

// POST form (triggers route action)
<Form method="post">
  <input name="title" />
  <textarea name="body" />
  <button type="submit">Create Post</button>
</Form>

// GET form (navigates with query string)
<Form method="get" action="/search">
  <input name="q" placeholder="Search..." />
  <button type="submit">Search</button>
</Form>

// DELETE-style mutation (use POST with intent)
<Form method="post">
  <input type="hidden" name="intent" value="delete" />
  <input type="hidden" name="id" value={item.id} />
  <button type="submit">Delete</button>
</Form>

// File upload
<Form method="post" encType="multipart/form-data">
  <input type="file" name="avatar" />
  <button type="submit">Upload</button>
</Form>

// Navigate without reloading
<Form method="post" navigate={false}>
  {/* Submits without navigating — useful with useFetcher alternative */}
</Form>

Navigate

Redirect on render (component-based redirect):

import { Navigate } from "react-router";

function ProtectedRoute({ children }) {
  const { user } = useAuth();
  if (!user) {
    return <Navigate to="/login" replace />;
  }
  return children;
}

Outlet

Renders the matching child route. Optionally pass context data to children:

import { Outlet, useOutletContext } from "react-router";

function Dashboard() {
  const [user, setUser] = useState(null);

  return (
    <div>
      <Sidebar />
      {/* Pass context to child routes */}
      <Outlet context={{ user, setUser }} />
    </div>
  );
}

// In a child route:
function DashboardSettings() {
  // Type the context for TypeScript safety
  const { user, setUser } = useOutletContext<{
    user: User | null;
    setUser: (u: User) => void;
  }>();

  return <SettingsForm user={user} onSave={setUser} />;
}

ScrollRestoration

Restores scroll position when navigating back/forward. Place it once in your root layout (data router or framework mode only):

import { ScrollRestoration } from "react-router";

// In your root layout
function Root() {
  return (
    <>
      <Outlet />
      <ScrollRestoration />
    </>
  );
}

// Custom scroll key — for example, scroll by pathname only, ignoring search params
<ScrollRestoration
  getKey={(location) => location.pathname}
/>

// Restore scroll per-element (not just window)
<ScrollRestoration
  getKey={(location) => {
    // Use different keys for different "tabs" at the same URL
    return location.pathname + location.search;
  }}
/>

Await

Render deferred data with a Suspense-compatible loading fallback:

import { Await, useLoaderData } from "react-router";
import { Suspense } from "react";

export async function loader() {
  return {
    user: await getUser(),                    // Awaited before render
    recommendations: getRecommendations(),    // Promise passed through (deferred)
  };
}

export default function Dashboard() {
  const { user, recommendations } = useLoaderData();

  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      <Suspense fallback={<p>Loading recommendations...</p>}>
        <Await resolve={recommendations}>
          {(items) => (
            <ul>
              {items.map((item) => (
                <li key={item.id}>{item.title}</li>
              ))}
            </ul>
          )}
        </Await>
      </Suspense>
    </div>
  );
}

The key insight: if you await a promise in the loader, the page waits for it before rendering. If you return the promise without await, the page renders immediately and the <Await> component streams in the data when it resolves.

4.6 Navigation Hooks

useNavigate

Programmatic navigation:

import { useNavigate } from "react-router";

function LoginForm() {
  const navigate = useNavigate();

  async function handleSubmit(event) {
    event.preventDefault();
    const success = await login(/* ... */);
    if (success) {
      navigate("/dashboard");
    }
  }

  return <form onSubmit={handleSubmit}>...</form>;
}

// Navigation options
navigate("/settings");                    // Push new entry
navigate("/settings", { replace: true }); // Replace current entry
navigate(-1);                             // Go back
navigate(-2);                             // Go back 2 entries
navigate(1);                              // Go forward
navigate("/login", {
  state: { from: location.pathname },     // Pass state data
});
navigate("/new-page", {
  viewTransition: true,                   // Animate the transition
});

useLocation

Access the current location object:

import { useLocation } from "react-router";

function Analytics() {
  const location = useLocation();

  useEffect(() => {
    trackPageView(location.pathname);
  }, [location]);

  return null;
}

The location object contains:

useParams

Access dynamic URL parameters:

import { useParams } from "react-router";

// Route: "/users/:userId/posts/:postId"
// URL: "/users/123/posts/456"

function Post() {
  const { userId, postId } = useParams();
  // userId === "123"
  // postId === "456"

  return <h1>Post {postId} by User {userId}</h1>;
}

All parameter values are strings. Parse numbers or other types explicitly:

const { id } = useParams();
const numericId = Number(id); // Convert when needed

useSearchParams

Read and update query string parameters without a full navigation:

import { useSearchParams } from "react-router";

function ProductList() {
  const [searchParams, setSearchParams] = useSearchParams();

  const category = searchParams.get("category");  // "shoes" or null
  const page = searchParams.get("page") || "1";

  function nextPage() {
    setSearchParams((prev) => {
      prev.set("page", String(Number(page) + 1));
      return prev;
    });
  }

  function setCategory(cat: string) {
    setSearchParams({ category: cat, page: "1" });
  }

  return (
    <div>
      <h1>Products{category ? `: ${category}` : ""} (Page {page})</h1>
      <button onClick={() => setCategory("shoes")}>Shoes</button>
      <button onClick={() => setCategory("hats")}>Hats</button>
      <button onClick={nextPage}>Next Page</button>
    </div>
  );
}

useSearchParams returns a tuple of [URLSearchParams, SetURLSearchParams], following the same pattern as React's useState.

useNavigation

Track the state of any in-progress navigation:

import { useNavigation } from "react-router";

function Root() {
  const navigation = useNavigation();

  return (
    <div>
      {navigation.state === "loading" && <GlobalSpinner />}
      {navigation.state === "submitting" && <p>Saving...</p>}
      <Outlet />
    </div>
  );
}

useBlocker

Block navigation when the user has unsaved changes:

import { useBlocker } from "react-router";

function EditForm() {
  const [isDirty, setIsDirty] = useState(false);
  const blocker = useBlocker(isDirty);

  return (
    <div>
      <form onChange={() => setIsDirty(true)}>
        <input name="title" />
        <button type="submit">Save</button>
      </form>

      {blocker.state === "blocked" && (
        <div className="modal">
          <p>You have unsaved changes. Leave anyway?</p>
          <button onClick={() => blocker.proceed()}>Leave</button>
          <button onClick={() => blocker.reset()}>Stay</button>
        </div>
      )}
    </div>
  );
}

The blocker has three states: "unblocked" (default), "blocked" (navigation attempted), and "proceeding" (user confirmed navigation).

useBeforeUnload

Warn before the user closes or reloads the browser tab:

import { useBeforeUnload } from "react-router";
import { useCallback } from "react";

function EditForm() {
  const [isDirty, setIsDirty] = useState(false);

  useBeforeUnload(
    useCallback(
      (event) => {
        if (isDirty) {
          event.preventDefault();
        }
      },
      [isDirty]
    )
  );

  return <form onChange={() => setIsDirty(true)}>...</form>;
}

Warning

useBeforeUnload only handles browser tab close/reload. For in-app navigation blocking, use useBlocker instead. You typically want both for full coverage.

4.7 Data Hooks

useLoaderData

Access the data returned by the current route's loader:

import { useLoaderData } from "react-router";

export async function loader() {
  const users = await db.users.findMany();
  return { users };
}

export default function Users() {
  const { users } = useLoaderData();
  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

In framework mode with typegen, the return type is inferred automatically from your loader function.

useActionData

Access the data returned by the current route's action (after a form submission):

import { useActionData, Form } from "react-router";

export async function action({ request }) {
  const formData = await request.formData();
  const email = formData.get("email") as string;

  const errors: Record<string, string> = {};
  if (!email) errors.email = "Email is required";
  else if (!email.includes("@")) errors.email = "Invalid email";

  if (Object.keys(errors).length > 0) {
    return { errors };
  }

  await createSubscriber(email);
  return { success: true };
}

export default function Newsletter() {
  const actionData = useActionData();

  return (
    <Form method="post">
      <label>
        Email
        <input name="email" type="email" />
      </label>
      {actionData?.errors?.email && (
        <p className="error">{actionData.errors.email}</p>
      )}
      {actionData?.success && <p className="success">Subscribed!</p>}
      <button type="submit">Subscribe</button>
    </Form>
  );
}

useActionData returns undefined on first render (no submission yet), then returns the action's return value after submission.

useRouteLoaderData

Access loader data from a parent or any ancestor route by its route ID:

import { useRouteLoaderData } from "react-router";

// In any child route component:
function UserAvatar() {
  // Access the root route's loader data
  // In data router mode, the route ID is the path or an explicit `id` property
  const rootData = useRouteLoaderData("root");
  if (!rootData?.user) return null;
  return <img src={rootData.user.avatarUrl} alt={rootData.user.name} />;
}

This is useful for accessing global data (current user, feature flags, site config) loaded in a root or layout route from deeply nested children.

useFetcher

Interact with loaders and actions without causing a navigation. This is the workhorse for in-place updates, auto-save, background operations, and any mutation that should not change the URL:

import { useFetcher } from "react-router";

function TodoItem({ todo }) {
  const fetcher = useFetcher();

  // Optimistic UI: use fetcher's submitted data if available
  const isComplete = fetcher.formData
    ? fetcher.formData.get("complete") === "true"
    : todo.complete;

  return (
    <li className={isComplete ? "completed" : ""}>
      <fetcher.Form method="post" action={`/todos/${todo.id}/toggle`}>
        <input type="hidden" name="complete" value={String(!todo.complete)} />
        <button type="submit" disabled={fetcher.state !== "idle"}>
          {isComplete ? "Done" : "Todo"}: {todo.title}
        </button>
      </fetcher.Form>
    </li>
  );
}

Load data without navigation:

function UserSearch() {
  const fetcher = useFetcher();
  const [query, setQuery] = useState("");

  useEffect(() => {
    if (query.length > 2) {
      fetcher.load(`/api/users?q=${encodeURIComponent(query)}`);
    }
  }, [query]);

  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search users..."
      />
      {fetcher.state === "loading" && <Spinner />}
      {fetcher.data && (
        <ul>
          {fetcher.data.users.map((u) => (
            <li key={u.id}>{u.name}</li>
          ))}
        </ul>
      )}
    </div>
  );
}

useFetchers

Access all active fetchers (useful for global pending indicators):

import { useFetchers } from "react-router";

function GlobalPendingIndicator() {
  const fetchers = useFetchers();
  const isSubmitting = fetchers.some((f) => f.state === "submitting");
  const isLoading = fetchers.some((f) => f.state === "loading");

  if (!isSubmitting && !isLoading) return null;
  return <div className="global-spinner" />;
}

useRevalidator

Manually trigger revalidation of all loader data:

import { useRevalidator } from "react-router";

function RefreshButton() {
  const revalidator = useRevalidator();

  return (
    <button
      onClick={() => revalidator.revalidate()}
      disabled={revalidator.state === "loading"}
    >
      {revalidator.state === "loading" ? "Refreshing..." : "Refresh Data"}
    </button>
  );
}

Common use cases for manual revalidation:

• Polling on an interval
• After a WebSocket message indicates server data changed
• After a user returns to the tab (visibility change)

useSubmit

Submit forms programmatically:

import { useSubmit } from "react-router";

// Auto-save on change
function AutoSaveForm() {
  const submit = useSubmit();

  function handleChange(event) {
    // Submit the entire form on any change
    submit(event.currentTarget.form, {
      method: "post",
      replace: true,
    });
  }

  return (
    <Form method="post">
      <textarea name="content" onChange={handleChange} />
    </Form>
  );
}

// Submit arbitrary data (not from a form)
function DeleteButton({ id }) {
  const submit = useSubmit();

  function handleDelete() {
    if (confirm("Are you sure?")) {
      submit(
        { intent: "delete", id },
        { method: "post", action: "/items" }
      );
    }
  }

  return <button onClick={handleDelete}>Delete</button>;
}

// Submit FormData directly
function FileUpload() {
  const submit = useSubmit();

  function handleFile(event) {
    const formData = new FormData();
    formData.set("file", event.target.files[0]);
    submit(formData, {
      method: "post",
      encType: "multipart/form-data",
    });
  }

  return <input type="file" onChange={handleFile} />;
}

4.8 URL and Path Utilities

useHref

Resolve a to value into a full href string:

import { useHref } from "react-router";

function ExternalForm() {
  // Resolves against the current basename
  const href = useHref("/submit");
  return <form action={href} method="post">...</form>;
}

useResolvedPath

Resolve a relative path against the current location:

import { useResolvedPath } from "react-router";

function Breadcrumb() {
  const resolved = useResolvedPath("..");
  // resolved.pathname — parent route's path
  return <Link to={resolved}>Back</Link>;
}

useMatch

Check if the current URL matches a specific pattern:

import { useMatch } from "react-router";

function AdminBadge() {
  const match = useMatch("/admin/*");
  if (!match) return null;
  return <span className="badge">Admin Area</span>;
}

// Access captured params
function UserBanner() {
  const match = useMatch("/users/:id");
  if (!match) return null;
  return <p>Viewing user {match.params.id}</p>;
}

useMatches

Get all matched routes in the current hierarchy. Each match includes the route's id, pathname, params, data (loader data), and handle:

import { useMatches } from "react-router";

function Breadcrumbs() {
  const matches = useMatches();

  return (
    <nav aria-label="breadcrumb">
      <ol>
        {matches
          .filter((match) => match.handle?.breadcrumb)
          .map((match) => (
            <Link key={match.id} to={match.pathname}>
              {typeof match.handle.breadcrumb === "function"
                ? match.handle.breadcrumb(match)
                : match.handle.breadcrumb}
            </Link>
          ))}
      </ol>
    </nav>
  );
}

useFormAction

Resolve the action URL for the current route:

import { useFormAction } from "react-router";

function InlineAction() {
  const action = useFormAction();
  // Resolves to the current route's action URL
  // Useful for constructing action URLs in nested routes
  return <Form method="post" action={action}>...</Form>;
}

useLinkClickHandler

Build custom navigation components with full control over click handling:

import { useLinkClickHandler } from "react-router";

function TrackedLink({ to, children, ...props }) {
  const handleClick = useLinkClickHandler(to);

  return (
    <a
      href={to}
      onClick={(event) => {
        analytics.track("link_click", { to });
        handleClick(event);
      }}
      {...props}
    >
      {children}
    </a>
  );
}

4.9 View Transitions

React Router integrates with the browser's View Transitions API for animated page transitions:

import { Link, NavLink, useNavigate, useViewTransitionState } from "react-router";

// Enable via Link
<Link to="/gallery/42" viewTransition>View Photo</Link>

// Enable via NavLink
<NavLink to="/page" viewTransition>Page</NavLink>

// Enable programmatically
const navigate = useNavigate();
navigate("/next", { viewTransition: true });

// Check transition state for CSS animations
function ImageCard({ id, src }) {
  const isTransitioning = useViewTransitionState(`/gallery/${id}`);

  return (
    <Link to={`/gallery/${id}`} viewTransition>
      <img
        src={src}
        style={{
          viewTransitionName: isTransitioning ? "hero-image" : "",
        }}
      />
    </Link>
  );
}