# React Router v7

React Router is a multi-strategy routing library for React that bridges the gap from React 18 to React 19. It serves as both a lightweight client-side routing library and a full-featured React framework with server-side rendering, streaming, and multi-platform deployment capabilities. The library provides platform-agnostic routing primitives through `react-router`, browser-specific bindings through `react-router-dom`, and comprehensive build tooling through `@react-router/dev`.

The architecture supports progressive enhancement, starting from basic HTML forms that work without JavaScript, to sophisticated client-side interactions with optimistic UI updates, prefetching, and view transitions. React Router v7 introduces advanced features like Single-Fetch data loading strategy, React Server Components integration, and unified request/response handling across Node.js, Cloudflare Workers, and other platforms through runtime adapters.

## Creating a Basic Router

Setup a client-side router with data loading and nested routes.

```tsx
import { createBrowserRouter, RouterProvider, useLoaderData } from "react-router-dom";

// Define loaders for data fetching
async function rootLoader() {
  const user = await fetch("/api/user").then(r => r.json());
  return { user };
}

async function todosLoader({ request, params }) {
  const url = new URL(request.url);
  const filter = url.searchParams.get("filter");
  const todos = await fetch(`/api/todos?filter=${filter}`).then(r => r.json());
  return { todos };
}

// Define route configuration
const router = createBrowserRouter([
  {
    path: "/",
    loader: rootLoader,
    Component: Root,
    errorElement: <ErrorBoundary />,
    children: [
      {
        index: true,
        Component: Home,
      },
      {
        path: "todos",
        loader: todosLoader,
        Component: TodosList,
      },
    ],
  },
]);

function Root() {
  const { user } = useLoaderData();
  return (
    <div>
      <nav>Hello {user.name}</nav>
      <Outlet /> {/* Nested routes render here */}
    </div>
  );
}

function TodosList() {
  const { todos } = useLoaderData();
  return (
    <ul>
      {todos.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  );
}

export default function App() {
  return <RouterProvider router={router} fallbackElement={<div>Loading...</div>} />;
}
```

## Form Submission with Actions

Handle form submissions with server actions and automatic revalidation.

```tsx
import { Form, useActionData, useNavigation, redirect } from "react-router-dom";

// Define action for handling form submissions
async function createTodoAction({ request, params }) {
  const formData = await request.formData();
  const title = formData.get("title");
  const description = formData.get("description");

  // Validate input
  if (!title || title.length < 3) {
    return { error: "Title must be at least 3 characters" };
  }

  // Create todo
  const todo = await fetch("/api/todos", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ title, description }),
  }).then(r => r.json());

  // Redirect to the new todo
  return redirect(`/todos/${todo.id}`);
}

const router = createBrowserRouter([
  {
    path: "/todos/new",
    action: createTodoAction,
    Component: NewTodoForm,
  },
]);

function NewTodoForm() {
  const actionData = useActionData();
  const navigation = useNavigation();
  const isSubmitting = navigation.state === "submitting";

  return (
    <Form method="post">
      <input
        name="title"
        type="text"
        placeholder="Todo title"
        disabled={isSubmitting}
      />
      {actionData?.error && <p className="error">{actionData.error}</p>}

      <textarea
        name="description"
        placeholder="Description"
        disabled={isSubmitting}
      />

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Creating..." : "Create Todo"}
      </button>
    </Form>
  );
}
```

## Navigation with Links

Create navigation links with prefetching and active state styling.

```tsx
import { Link, NavLink } from "react-router-dom";

function Navigation() {
  return (
    <nav>
      {/* Basic link */}
      <Link to="/dashboard">Dashboard</Link>

      {/* Link with state */}
      <Link
        to="/profile"
        state={{ from: "navigation" }}
      >
        Profile
      </Link>

      {/* Link with prefetching */}
      <Link
        to="/heavy-page"
        prefetch="intent"  // Prefetch on hover/focus
      >
        Heavy Page
      </Link>

      {/* NavLink with active styling */}
      <NavLink
        to="/settings"
        className={({ isActive, isPending }) =>
          isActive ? "active" : isPending ? "pending" : ""
        }
        style={({ isActive }) => ({
          fontWeight: isActive ? "bold" : "normal"
        })}
      >
        Settings
      </NavLink>

      {/* Relative navigation */}
      <Link to=".." relative="path">Go Back</Link>
    </nav>
  );
}
```

## Using Fetchers for Non-Navigation Submissions

Submit data without navigation using fetchers for dynamic interfaces.

```tsx
import { useFetcher, useFetchers } from "react-router-dom";

function TodoItem({ todo }) {
  const fetcher = useFetcher();
  const isDeleting = fetcher.state === "submitting";
  const isOptimistic = fetcher.formData?.get("completed") === "true";

  return (
    <div style={{ opacity: isDeleting ? 0.5 : 1 }}>
      <fetcher.Form method="post" action={`/todos/${todo.id}/toggle`}>
        <input
          type="checkbox"
          name="completed"
          value="true"
          checked={isOptimistic || todo.completed}
          onChange={(e) => fetcher.submit(e.currentTarget.form)}
        />
        <span>{todo.title}</span>
      </fetcher.Form>

      <fetcher.Form method="delete" action={`/todos/${todo.id}`}>
        <button type="submit" disabled={isDeleting}>
          {isDeleting ? "Deleting..." : "Delete"}
        </button>
      </fetcher.Form>
    </div>
  );
}

// Display loading state for all active fetchers
function GlobalLoadingIndicator() {
  const fetchers = useFetchers();
  const isLoading = fetchers.some(f => f.state !== "idle");

  return isLoading ? <div className="spinner">Loading...</div> : null;
}

// Action handler for toggle
async function toggleTodoAction({ request, params }) {
  const formData = await request.formData();
  const completed = formData.get("completed") === "true";

  await fetch(`/api/todos/${params.id}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ completed }),
  });

  return { ok: true };
}
```

## Programmatic Navigation

Navigate programmatically in response to events or application logic.

```tsx
import { useNavigate, useLocation, useSearchParams } from "react-router-dom";

function SearchableList() {
  const navigate = useNavigate();
  const location = useLocation();
  const [searchParams, setSearchParams] = useSearchParams();

  const currentQuery = searchParams.get("q") || "";

  function handleSearch(query) {
    // Update URL search params
    setSearchParams({ q: query });
  }

  function handleSelect(id) {
    // Navigate with state
    navigate(`/items/${id}`, {
      state: { from: location.pathname },
      replace: false,
    });
  }

  function handleCancel() {
    // Go back
    navigate(-1);
  }

  function handleReset() {
    // Navigate and replace history entry
    navigate("/", { replace: true });
  }

  return (
    <div>
      <input
        type="search"
        value={currentQuery}
        onChange={(e) => handleSearch(e.target.value)}
      />

      <button onClick={handleCancel}>Back</button>
      <button onClick={handleReset}>Reset</button>
    </div>
  );
}
```

## Route Parameters and Matching

Access dynamic route parameters and match patterns.

```tsx
import { useParams, useMatches, useRouteLoaderData } from "react-router-dom";

// Route configuration
const router = createBrowserRouter([
  {
    id: "root",
    path: "/",
    loader: rootLoader,
    children: [
      {
        path: "users/:userId/posts/:postId",
        loader: postLoader,
        Component: PostDetail,
      },
    ],
  },
]);

function PostDetail() {
  // Access route parameters
  const { userId, postId } = useParams();
  const { post } = useLoaderData();

  // Access parent route data
  const rootData = useRouteLoaderData("root");

  // Access all matched routes
  const matches = useMatches();
  const breadcrumbs = matches
    .filter(match => match.handle?.crumb)
    .map(match => match.handle.crumb(match.data));

  return (
    <article>
      <nav>{breadcrumbs}</nav>
      <h1>{post.title}</h1>
      <p>By user {userId}</p>
    </article>
  );
}

async function postLoader({ params }) {
  const post = await fetch(`/api/users/${params.userId}/posts/${params.postId}`)
    .then(r => r.json());
  return { post };
}
```

## Server-Side Session Management

Create and manage user sessions with cookie-based storage.

```tsx
import { createCookie, createCookieSessionStorage } from "@react-router/node";

// Create session storage
const sessionCookie = createCookie("__session", {
  secrets: ["s3cr3t1"],
  httpOnly: true,
  secure: process.env.NODE_ENV === "production",
  sameSite: "lax",
  maxAge: 60 * 60 * 24 * 7, // 1 week
});

const sessionStorage = createCookieSessionStorage({
  cookie: sessionCookie,
});

// Loader: read session
async function loader({ request }) {
  const session = await sessionStorage.getSession(
    request.headers.get("Cookie")
  );

  const userId = session.get("userId");
  if (!userId) {
    throw redirect("/login");
  }

  const user = await db.user.findUnique({ where: { id: userId } });
  return { user };
}

// Action: write session
async function loginAction({ request }) {
  const formData = await request.formData();
  const email = formData.get("email");
  const password = formData.get("password");

  const user = await verifyLogin(email, password);
  if (!user) {
    return { error: "Invalid credentials" };
  }

  const session = await sessionStorage.getSession();
  session.set("userId", user.id);

  return redirect("/dashboard", {
    headers: {
      "Set-Cookie": await sessionStorage.commitSession(session),
    },
  });
}

// Action: destroy session
async function logoutAction({ request }) {
  const session = await sessionStorage.getSession(
    request.headers.get("Cookie")
  );

  return redirect("/", {
    headers: {
      "Set-Cookie": await sessionStorage.destroySession(session),
    },
  });
}
```

## Flash Messages with Sessions

Store temporary messages that persist across redirects.

```tsx
import { createCookieSessionStorage, redirect } from "@react-router/node";
import { useLoaderData } from "react-router-dom";

const sessionStorage = createCookieSessionStorage({
  cookie: {
    name: "__session",
    secrets: ["s3cr3t1"],
    sameSite: "lax",
  },
});

async function getSession(request) {
  return sessionStorage.getSession(request.headers.get("Cookie"));
}

// Action: set flash message
async function deleteAction({ request, params }) {
  const session = await getSession(request);

  try {
    await db.todo.delete({ where: { id: params.id } });
    session.flash("success", "Todo deleted successfully");
  } catch (error) {
    session.flash("error", "Failed to delete todo");
  }

  return redirect("/todos", {
    headers: {
      "Set-Cookie": await sessionStorage.commitSession(session),
    },
  });
}

// Loader: read flash message
async function loader({ request }) {
  const session = await getSession(request);
  const success = session.get("success");
  const error = session.get("error");

  return {
    success,
    error,
  };
}

function TodosPage() {
  const { success, error } = useLoaderData();

  return (
    <div>
      {success && <div className="alert success">{success}</div>}
      {error && <div className="alert error">{error}</div>}
      {/* Rest of page */}
    </div>
  );
}
```

## File-Based Session Storage

Use file system for session persistence in Node.js environments.

```tsx
import { createFileSessionStorage } from "@react-router/node";
import { join } from "path";

const sessionStorage = createFileSessionStorage({
  dir: join(process.cwd(), ".sessions"),
  cookie: {
    name: "__session",
    secrets: ["s3cr3t1"],
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
    maxAge: 60 * 60 * 24 * 30, // 30 days
  },
});

async function cartLoader({ request }) {
  const session = await sessionStorage.getSession(
    request.headers.get("Cookie")
  );

  const cart = session.get("cart") || [];
  return { cart };
}

async function addToCartAction({ request }) {
  const session = await sessionStorage.getSession(
    request.headers.get("Cookie")
  );

  const formData = await request.formData();
  const productId = formData.get("productId");

  const cart = session.get("cart") || [];
  cart.push(productId);
  session.set("cart", cart);

  return redirect("/cart", {
    headers: {
      "Set-Cookie": await sessionStorage.commitSession(session),
    },
  });
}
```

## Cloudflare Workers KV Session Storage

Store sessions in Cloudflare Workers KV for edge deployments.

```tsx
import { createWorkersKVSessionStorage } from "@react-router/cloudflare";

// In app/sessions.server.ts
export function createSessionStorage(kv: KVNamespace) {
  return createWorkersKVSessionStorage({
    kv,
    cookie: {
      name: "__session",
      secrets: ["s3cr3t1"],
      sameSite: "lax",
      httpOnly: true,
      secure: true,
    },
  });
}

// In route loader
async function loader({ request, context }) {
  const sessionStorage = createSessionStorage(context.env.SESSIONS_KV);
  const session = await sessionStorage.getSession(
    request.headers.get("Cookie")
  );

  const userId = session.get("userId");
  return { userId };
}

// In route action
async function action({ request, context }) {
  const sessionStorage = createSessionStorage(context.env.SESSIONS_KV);
  const session = await sessionStorage.getSession(
    request.headers.get("Cookie")
  );

  session.set("userId", "user-123");

  return redirect("/dashboard", {
    headers: {
      "Set-Cookie": await sessionStorage.commitSession(session),
    },
  });
}
```

## Error Boundaries

Handle errors at route level with error boundaries and error states.

```tsx
import { useRouteError, isRouteErrorResponse, Link } from "react-router-dom";

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    errorElement: <RootErrorBoundary />,
    children: [
      {
        path: "todos/:id",
        loader: todoLoader,
        Component: TodoDetail,
        errorElement: <TodoErrorBoundary />,
      },
    ],
  },
]);

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

  if (isRouteErrorResponse(error)) {
    return (
      <div>
        <h1>{error.status} {error.statusText}</h1>
        <p>{error.data}</p>
        <Link to="/">Go Home</Link>
      </div>
    );
  }

  return (
    <div>
      <h1>Something went wrong</h1>
      <p>{error.message}</p>
      <Link to="/">Go Home</Link>
    </div>
  );
}

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

  if (isRouteErrorResponse(error) && error.status === 404) {
    return (
      <div>
        <h2>Todo not found</h2>
        <Link to="/todos">Back to todos</Link>
      </div>
    );
  }

  throw error; // Rethrow to parent boundary
}

async function todoLoader({ params }) {
  const todo = await fetch(`/api/todos/${params.id}`).then(r => {
    if (!r.ok) {
      throw new Response("Not Found", { status: 404 });
    }
    return r.json();
  });

  return { todo };
}
```

## Deferred Data Loading

Stream data to the client as it becomes available using deferred loading.

```tsx
import { defer, Await, useLoaderData } from "react-router-dom";
import { Suspense } from "react";

async function loader({ params }) {
  // Fast data - await immediately
  const product = await fetchProduct(params.id);

  // Slow data - defer loading
  const reviews = fetchReviews(params.id); // Don't await
  const recommendations = fetchRecommendations(params.id); // Don't await

  return defer({
    product,
    reviews,
    recommendations,
  });
}

function ProductPage() {
  const { product, reviews, recommendations } = useLoaderData();

  return (
    <div>
      {/* Render immediately */}
      <h1>{product.name}</h1>
      <p>{product.description}</p>

      {/* Stream in when ready */}
      <Suspense fallback={<div>Loading reviews...</div>}>
        <Await
          resolve={reviews}
          errorElement={<div>Error loading reviews</div>}
        >
          {(reviewsData) => (
            <div>
              <h2>Reviews</h2>
              {reviewsData.map(review => (
                <div key={review.id}>{review.text}</div>
              ))}
            </div>
          )}
        </Await>
      </Suspense>

      <Suspense fallback={<div>Loading recommendations...</div>}>
        <Await resolve={recommendations}>
          {(recs) => (
            <div>
              <h2>You might also like</h2>
              {recs.map(rec => (
                <Link key={rec.id} to={`/products/${rec.id}`}>
                  {rec.name}
                </Link>
              ))}
            </div>
          )}
        </Await>
      </Suspense>
    </div>
  );
}
```

## Server Request Handler

Create a server request handler for Node.js or other platforms.

```tsx
import { createRequestHandler } from "@react-router/node";
import * as build from "./build/server/index.js";

// Create request handler
const handler = createRequestHandler({
  build,
  mode: process.env.NODE_ENV,
  getLoadContext: (req, res) => ({
    db: initDatabase(),
    user: req.user,
  }),
});

// Use with Express
import express from "express";
const app = express();

app.all("*", handler);

app.listen(3000, () => {
  console.log("Server running on http://localhost:3000");
});

// Use with native Node.js HTTP server
import { createServer } from "http";
import { createRequestListener } from "@react-router/node";

const server = createServer(
  createRequestListener({
    build,
    mode: process.env.NODE_ENV,
  })
);

server.listen(3000);
```

## Type-Safe Route Data

Leverage TypeScript for type-safe loader and action data.

```tsx
import type { LoaderFunctionArgs, ActionFunctionArgs } from "react-router-dom";
import { useLoaderData, useActionData } from "react-router-dom";

interface Todo {
  id: string;
  title: string;
  completed: boolean;
}

async function loader({ params }: LoaderFunctionArgs) {
  const todos = await db.todo.findMany();
  return { todos };
}

async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const title = formData.get("title") as string;

  if (!title) {
    return { error: "Title is required" };
  }

  const todo = await db.todo.create({ data: { title } });
  return { todo };
}

function TodosPage() {
  // Type inferred from loader return type
  const { todos } = useLoaderData<typeof loader>();
  const actionData = useActionData<typeof action>();

  return (
    <div>
      {actionData?.error && <p>{actionData.error}</p>}
      {actionData?.todo && <p>Created: {actionData.todo.title}</p>}

      <ul>
        {todos.map(todo => (
          <li key={todo.id}>{todo.title}</li>
        ))}
      </ul>
    </div>
  );
}
```

## Blocking Navigation

Prevent navigation when there are unsaved changes.

```tsx
import { useBlocker } from "react-router-dom";
import { useState } from "react";

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

  const blocker = useBlocker(
    ({ currentLocation, nextLocation }) =>
      isDirty && currentLocation.pathname !== nextLocation.pathname
  );

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

      {blocker.state === "blocked" && (
        <div className="modal">
          <p>You have unsaved changes. Are you sure you want to leave?</p>
          <button onClick={() => blocker.proceed()}>Leave</button>
          <button onClick={() => blocker.reset()}>Stay</button>
        </div>
      )}
    </>
  );
}
```

## View Transitions

Enable smooth visual transitions between routes using the View Transitions API.

```tsx
import { Link, useViewTransitionState } from "react-router-dom";

function Navigation() {
  return (
    <nav>
      {/* Enable view transition for this navigation */}
      <Link to="/about" viewTransition>
        About
      </Link>
    </nav>
  );
}

function Thumbnail({ id, image }) {
  // Check if this route is transitioning
  const isTransitioning = useViewTransitionState(`/photos/${id}`);

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

// In CSS
/*
::view-transition-old(photo-expand),
::view-transition-new(photo-expand) {
  animation-duration: 0.5s;
}
*/
```

## React Router serves as both a minimalist routing library for existing React applications and a comprehensive framework for building full-stack web applications. In library mode, it provides declarative routing, data loading, and form handling that integrates seamlessly with any React setup. In framework mode with `@react-router/dev`, it delivers a complete solution with file-based routing, automatic code splitting, server-side rendering with streaming, and unified deployment across Node.js, Cloudflare Workers, and other platforms.

The integration patterns range from simple client-side routing with `createBrowserRouter()` to advanced server implementations with loaders, actions, and session management. The library's progressive enhancement philosophy ensures applications remain functional without JavaScript while enabling sophisticated interactions when available. Data loading strategies support both traditional waterfall loading and modern patterns like Single-Fetch for optimized performance. Session management abstractions work across cookie-based, file-based, and key-value storage backends, making it straightforward to build authentication and stateful features that work consistently across deployment targets.