React Router Data Mode

React Router Data Mode

Data mode uses createBrowserRouter and RouterProvider to enable data loading, actions, and pending UI without the framework's Vite plugin. This is ideal for existing React applications that want to add data loading and mutation capabilities.

When to Apply

• Using createBrowserRouter with route objects
• Loading data with loader property on routes
• Handling mutations with action property
• Navigating with <Link>, <NavLink>, <Form>, redirect, and useNavigate
• Implementing pending/loading UI states with useNavigation
• Using useFetcher for mutations without navigation

References

Load the relevant reference for detailed guidance on the specific API/concept:

Critical Patterns

These are the most important patterns to follow. Load the relevant reference for full details.

Basic Router Setup

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

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    children: [
      { index: true, Component: Home },
      { path: "about", Component: About },
    ],
  },
]);

ReactDOM.createRoot(root).render(<RouterProvider router={router} />);

Forms & Mutations

Search forms - use <Form method="get">, NOT onSubmit with setSearchParams:

// ✅ Correct
<Form method="get">
  <input name="q" />
</Form>

// ❌ Wrong - don't manually handle search params
<form onSubmit={(e) => { e.preventDefault(); setSearchParams(...) }}>

Inline mutations - use useFetcher, NOT <Form> (which causes page navigation):

const fetcher = useFetcher();
const optimistic = fetcher.formData
  ? fetcher.formData.get("favorite") === "true"
  : isFavorite;

<fetcher.Form method="post" action={`/favorites/${id}`}>
  <button>{optimistic ? "★" : "☆"}</button>
</fetcher.Form>;

See references/actions.md for complete patterns.

Optimistic UI Pattern

Use fetcher.formData to show expected results immediately:

function FavoriteButton({ itemId, isFavorite }) {
  const fetcher = useFetcher();

  // Optimistic: use pending form data, fallback to server state
  const optimistic = fetcher.formData
    ? fetcher.formData.get("favorite") === "true"
    : isFavorite;

  return (
    <fetcher.Form method="post" action={`/items/${itemId}/favorite`}>
      <input type="hidden" name="favorite" value={String(!optimistic)} />
      <button>{optimistic ? "★" : "☆"}</button>
    </fetcher.Form>
  );
}

See references/pending-ui.md for complete patterns.

Further Documentation

If anything related to React Router is not covered in these references, you can search the official documentation:

https://reactrouter.com/docs

Actions and Form Handling

Actions handle data mutations (create, update, delete). After an action completes, all loaders on the page automatically revalidate.

Choosing the Right Pattern

Default to `useFetcher` for mutations - it provides smoother UX with optimistic updates and no page reload.

Anti-Patterns to Avoid

// ❌ DON'T: Manual form handling for search
function SearchForm() {
  const [searchParams, setSearchParams] = useSearchParams();

  function onSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    setSearchParams({ q: formData.get("q") as string });
  }

  return (
    <form onSubmit={onSubmit}>
      <input name="q" />
      <button type="submit">Search</button>
    </form>
  );
}

// ✅ DO: Use Form with method="get" - handles search params automatically
function SearchForm() {
  return (
    <Form method="get">
      <input name="q" />
      <button type="submit">Search</button>
    </Form>
  );
}

// ❌ DON'T: Use Form for inline mutations (causes full navigation)
function RatingButton({ itemId }) {
  return (
    <Form method="post" action={`/items/${itemId}/rate`}>
      <button>Rate</button>
    </Form>
  );
}

// ✅ DO: Use useFetcher for inline mutations (no navigation, smoother UX)
function RatingButton({ itemId, currentRating }) {
  const fetcher = useFetcher();

  // Optimistic UI - show expected state immediately
  const optimisticRating = fetcher.formData
    ? Number(fetcher.formData.get("rating"))
    : currentRating;

  return (
    <fetcher.Form method="post" action={`/items/${itemId}/rate`}>
      <input type="hidden" name="rating" value={optimisticRating + 1} />
      <button>⭐ {optimisticRating}</button>
    </fetcher.Form>
  );
}

---

Defining Actions on Routes

Actions are defined on route objects and handle form submissions:

import { redirect } from "react-router";

const router = createBrowserRouter([
  {
    path: "/projects/new",
    action: async ({ request }) => {
      const formData = await request.formData();
      const title = formData.get("title");

      const project = await db.createProject({ title });

      return redirect(`/projects/${project.id}`);
    },
    Component: NewProject,
  },
]);

Action Arguments

• request - The Fetch Request object with form data
• params - URL parameters from dynamic segments

{
  path: "/projects/:projectId",
  action: async ({ request, params }) => {
    const formData = await request.formData();
    await db.updateProject(params.projectId, {
      title: formData.get("title"),
    });
    return { success: true };
  },
  Component: EditProject,
}

---

Search Forms with GET

<Form method="get"> automatically serializes inputs to URL search params:

import { Form, useSearchParams, useLoaderData } from "react-router";

const router = createBrowserRouter([
  {
    path: "/search",
    loader: async ({ request }) => {
      const url = new URL(request.url);
      const query = url.searchParams.get("q") ?? "";
      return { results: await search(query) };
    },
    Component: SearchPage,
  },
]);

function SearchPage() {
  const [searchParams] = useSearchParams();
  const { results } = useLoaderData();
  const query = searchParams.get("q") ?? "";

  return (
    <div>
      <Form method="get">
        <input type="text" name="q" defaultValue={query} />
        <button type="submit">Search</button>
      </Form>
      <SearchResults results={results} />
    </div>
  );
}

---

Form Component

The <Form> component submits to actions and handles navigation:

import { Form } from "react-router";

function NewProject() {
  return (
    <Form method="post">
      <input type="text" name="title" required />
      <button type="submit">Create</button>
    </Form>
  );
}

Form Props

• method - HTTP method: "get", "post", "put", "delete", "patch"
• action - URL to submit to (defaults to current route)
• navigate - Set to false to prevent navigation after submission

<Form method="post" action="/projects/new">
  {/* ... */}
</Form>

---

useSubmit

Submit forms programmatically:

import { useSubmit } from "react-router";

function AutoSave({ data }) {
  const submit = useSubmit();

  useEffect(() => {
    const timeout = setTimeout(() => {
      submit(data, { method: "post" });
    }, 1000);

    return () => clearTimeout(timeout);
  }, [data, submit]);

  return null;
}

---

useFetcher (Preferred for Mutations)

Use `useFetcher` as the default for mutations - it provides independent state, no page navigation, and enables optimistic UI.

Basic Usage

import { useFetcher } from "react-router";

function LikeButton({ postId }) {
  const fetcher = useFetcher();
  const isLiking = fetcher.state === "submitting";

  return (
    <fetcher.Form method="post" action={`/posts/${postId}/like`}>
      <button disabled={isLiking}>{isLiking ? "Liking..." : "Like"}</button>
    </fetcher.Form>
  );
}

Optimistic UI Pattern (Recommended)

Use fetcher.formData to show expected results immediately:

function FavoriteButton({ itemId, isFavorite }) {
  const fetcher = useFetcher();

  // Optimistic: use pending form data, fallback to server state
  const optimistic = fetcher.formData
    ? fetcher.formData.get("favorite") === "true"
    : isFavorite;

  return (
    <fetcher.Form method="post" action={`/items/${itemId}/favorite`}>
      <input type="hidden" name="favorite" value={String(!optimistic)} />
      <button>{optimistic ? "★" : "☆"}</button>
    </fetcher.Form>
  );
}

Fetcher Properties

• fetcher.state - "idle", "submitting", or "loading"
• fetcher.data - Data returned from the action
• fetcher.formData - FormData being submitted (use for optimistic UI)
• fetcher.Form - Form component scoped to this fetcher
• fetcher.submit() - Submit programmatically

---

useActionData

Access data returned from the current route's action:

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

const router = createBrowserRouter([
  {
    path: "/signup",
    action: async ({ request }) => {
      const formData = await request.formData();
      const email = formData.get("email");

      const errors = {};
      if (!email?.toString().includes("@")) {
        errors.email = "Invalid email address";
      }

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

      await createUser({ email });
      return redirect("/dashboard");
    },
    Component: Signup,
  },
]);

function Signup() {
  const actionData = useActionData();

  return (
    <Form method="post">
      <input type="email" name="email" />
      {actionData?.errors?.email && <span>{actionData.errors.email}</span>}
      <button type="submit">Sign Up</button>
    </Form>
  );
}

---

Form Validation Pattern

{
  path: "/register",
  action: async ({ request }) => {
    const formData = await request.formData();
    const email = String(formData.get("email"));
    const password = String(formData.get("password"));

    const errors: Record<string, string> = {};

    if (!email.includes("@")) {
      errors.email = "Invalid email address";
    }

    if (password.length < 12) {
      errors.password = "Password must be at least 12 characters";
    }

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

    // Validation passed
    await createAccount({ email, password });
    return redirect("/dashboard");
  },
  Component: Register,
}

---

Multiple Actions per Route

Use a hidden input or button name to distinguish intents:

{
  path: "/projects/:projectId",
  action: async ({ request, params }) => {
    const formData = await request.formData();
    const intent = formData.get("intent");

    switch (intent) {
      case "update":
        return updateProject(params.projectId, formData);
      case "delete":
        await deleteProject(params.projectId);
        return redirect("/projects");
      default:
        throw new Response("Invalid intent", { status: 400 });
    }
  },
  Component: Project,
}

// In component
function Project() {
  return (
    <Form method="post">
      <input name="title" />
      <button name="intent" value="update">Save</button>
      <button name="intent" value="delete">Delete</button>
    </Form>
  );
}

---

Fetcher with Action Data

Access data returned from fetcher actions:

function SignupForm() {
  const fetcher = useFetcher();
  const errors = fetcher.data?.errors;

  return (
    <fetcher.Form method="post" action="/signup">
      <input type="email" name="email" />
      {errors?.email && <span>{errors.email}</span>}
      <button type="submit">Sign Up</button>
    </fetcher.Form>
  );
}

---

See Also

• pending-ui.md - Optimistic UI and loading states
• data-loading.md - Loading data with loaders
• React Router Actions Documentation

Data Loading

Data is loaded using loader functions defined on route objects. Loaders run before the component renders and their data is accessed via the useLoaderData hook.

Basic Loader

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

const router = createBrowserRouter([
  {
    path: "/teams/:teamId",
    loader: async ({ params }) => {
      return fetchTeam(params.teamId);
    },
    Component: Team,
  },
]);

function Team() {
  const data = useLoaderData();
  return <h1>{data.name}</h1>;
}

Loader Arguments

Loaders receive an object with:

• params - URL parameters from dynamic segments
• request - The Fetch Request object

{
  path: "/products/:productId",
  loader: async ({ params, request }) => {
    // Access route params
    const productId = params.productId;

    // Access search params from request
    const url = new URL(request.url);
    const sort = url.searchParams.get("sort");

    return fetchProduct(productId, { sort });
  },
  Component: Product,
}

Using Request for Search Params

{
  path: "/search",
  loader: async ({ request }) => {
    const url = new URL(request.url);
    const query = url.searchParams.get("q") ?? "";
    const page = Number(url.searchParams.get("page")) || 1;

    return search(query, { page });
  },
  Component: SearchResults,
}

Using Request Signal for Cancellation

{
  path: "/search",
  loader: async ({ request }) => {
    const url = new URL(request.url);
    const query = url.searchParams.get("q");

    // Pass signal to abort request if user navigates away
    const results = await fetch(`/api/search?q=${query}`, {
      signal: request.signal,
    });

    return results.json();
  },
  Component: SearchResults,
}

Returning Data

Loaders can return any serializable data:

// Return object
loader: async () => {
  return { users: await fetchUsers() };
}

// Return array
loader: async () => {
  return fetchProducts();
}

// Return Response object
loader: async () => {
  const data = await fetchData();
  return Response.json(data, {
    headers: { "Cache-Control": "max-age=3600" },
  });
}

Throwing Errors

Throw responses to trigger error boundaries:

{
  path: "/teams/:teamId",
  loader: async ({ params }) => {
    const team = await fetchTeam(params.teamId);

    if (!team) {
      throw new Response("Not Found", { status: 404 });
    }

    return team;
  },
  ErrorBoundary: TeamError,
  Component: Team,
}

Throwing Redirects

Redirect from loaders using the redirect function:

import { redirect } from "react-router";

{
  path: "/dashboard",
  loader: async ({ request }) => {
    const user = await getUser(request);

    if (!user) {
      throw redirect("/login");
    }

    return user;
  },
  Component: Dashboard,
}

Redirect with Search Params

loader: async ({ request }) => {
  const user = await getUser(request);

  if (!user) {
    const url = new URL(request.url);
    throw redirect(`/login?returnTo=${encodeURIComponent(url.pathname)}`);
  }

  return user;
}

Parallel Data Loading

React Router loads data for all matched routes in parallel. Parent and child loaders run simultaneously:

const router = createBrowserRouter([
  {
    path: "/",
    loader: rootLoader, // Runs in parallel with child loaders
    Component: Root,
    children: [
      {
        path: "teams/:teamId",
        loader: teamLoader, // Runs in parallel with root loader
        Component: Team,
        children: [
          {
            path: "members",
            loader: membersLoader, // All three run in parallel
            Component: Members,
          },
        ],
      },
    ],
  },
]);

This eliminates waterfall requests common with useEffect data fetching.

Revalidation

After actions complete, all loaders on the page automatically revalidate to keep data fresh. Control this with shouldRevalidate:

{
  path: "/products",
  loader: productsLoader,
  shouldRevalidate: ({ currentUrl, nextUrl, defaultShouldRevalidate }) => {
    // Skip revalidation for query-only changes
    if (currentUrl.pathname === nextUrl.pathname) {
      return false;
    }
    return defaultShouldRevalidate;
  },
  Component: Products,
}

Multiple Loaders in Nested Routes

Each route can have its own loader. Access parent data with useRouteLoaderData:

import { useRouteLoaderData } from "react-router";

const router = createBrowserRouter([
  {
    id: "root",
    path: "/",
    loader: async () => {
      return { user: await getCurrentUser() };
    },
    Component: Root,
    children: [
      {
        path: "dashboard",
        loader: async () => {
          return { stats: await getDashboardStats() };
        },
        Component: Dashboard,
      },
    ],
  },
]);

function Dashboard() {
  const dashboardData = useLoaderData(); // { stats: ... }
  const rootData = useRouteLoaderData("root"); // { user: ... }

  return (
    <div>
      <h1>Welcome, {rootData.user.name}</h1>
      <Stats data={dashboardData.stats} />
    </div>
  );
}

Complete Example

import {
  createBrowserRouter,
  RouterProvider,
  useLoaderData,
  useParams,
  redirect,
} from "react-router";

const router = createBrowserRouter([
  {
    path: "/",
    loader: async () => {
      return { user: await getCurrentUser() };
    },
    Component: Root,
    children: [
      { index: true, Component: Home },
      {
        path: "teams/:teamId",
        loader: async ({ params, request }) => {
          const user = await getUser(request);
          if (!user) {
            throw redirect("/login");
          }

          const team = await fetchTeam(params.teamId);
          if (!team) {
            throw new Response("Not Found", { status: 404 });
          }

          return { team };
        },
        Component: Team,
      },
    ],
  },
]);

function Team() {
  const { team } = useLoaderData();
  const { teamId } = useParams();

  return (
    <div>
      <h1>{team.name}</h1>
      <p>Team ID: {teamId}</p>
    </div>
  );
}

ReactDOM.createRoot(document.getElementById("root")).render(
  <RouterProvider router={router} />
);

See Also

• route-object.md - All route object properties
• actions.md - Form handling and mutations
• React Router Loaders Documentation

Navigation

React Router provides several ways to navigate between routes.

Link Component

Basic navigation with the <Link> component:

import { Link } from "react-router";

function Nav() {
  return (
    <nav>
      <Link to="/">Home</Link>
      <Link to="/about">About</Link>
      <Link to="/products/123">Product</Link>
    </nav>
  );
}

Link Props

• to - Destination path (string or object)
• replace - Replace current history entry instead of pushing
• state - Pass state to the destination
• preventScrollReset - Prevent scroll position reset

<Link to="/dashboard" replace state={{ from: "home" }}>
  Dashboard
</Link>

---

NavLink Component

Link with active and pending state awareness:

import { NavLink } from "react-router";

function Nav() {
  return (
    <nav>
      <NavLink
        to="/"
        end
        className={({ isActive }) => (isActive ? "active" : "")}
      >
        Home
      </NavLink>

      <NavLink
        to="/products"
        className={({ isActive, isPending }) =>
          isPending ? "pending" : isActive ? "active" : ""
        }
      >
        Products
      </NavLink>
    </nav>
  );
}

NavLink Props

• end - Only match if the path is exact (not just a prefix)
• className - String or function receiving { isActive, isPending }
• style - Object or function receiving { isActive, isPending }
• children - Can be a function receiving { isActive, isPending }

<NavLink to="/messages">
  {({ isActive, isPending }) => (
    <span>Messages {isPending && <Spinner />}</span>
  )}
</NavLink>

isPending State

The isPending prop is true when navigating TO this link (while the loader runs):

<NavLink
  to="/dashboard"
  className={({ isPending }) => (isPending ? "loading" : "")}
>
  Dashboard
</NavLink>

---

useNavigate Hook

Programmatic navigation:

import { useNavigate } from "react-router";

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

  async function handleLogout() {
    await logout();
    navigate("/login");
  }

  return <button onClick={handleLogout}>Logout</button>;
}

Navigate Options

const navigate = useNavigate();

// Basic navigation
navigate("/dashboard");

// Replace history entry
navigate("/login", { replace: true });

// Pass state
navigate("/checkout", { state: { cartId: "abc" } });

// Go back/forward
navigate(-1); // Back
navigate(1); // Forward

---

redirect Function

Redirect from loaders and actions:

import { redirect } from "react-router";

const router = createBrowserRouter([
  {
    path: "/dashboard",
    loader: async ({ request }) => {
      const user = await getUser(request);

      if (!user) {
        throw redirect("/login");
      }

      return user;
    },
    Component: Dashboard,
  },
  {
    path: "/projects/new",
    action: async ({ request }) => {
      const project = await createProject(request);
      return redirect(`/projects/${project.id}`);
    },
    Component: NewProject,
  },
]);

Redirect with Status

// Temporary redirect (302, default)
throw redirect("/new-location");

// Permanent redirect (301)
throw redirect("/new-location", { status: 301 });

---

Form Navigation

Forms with method="get" navigate with search params:

import { Form } from "react-router";

function SearchForm() {
  return (
    <Form method="get" action="/search">
      <input type="text" name="q" />
      <button type="submit">Search</button>
    </Form>
  );
}
// Navigates to /search?q=...

Forms with method="post" submit to actions:

function NewProject() {
  return (
    <Form method="post" action="/projects">
      <input type="text" name="title" />
      <button type="submit">Create</button>
    </Form>
  );
}
// Submits to /projects action, then redirects

---

Relative Navigation

Paths are relative to the current route:

// If current URL is /products/123

<Link to="reviews">     // → /products/123/reviews
<Link to="../456">      // → /products/456
<Link to="..">          // → /products

Use relative="path" for path-based relativity instead of route-based:

<Link to=".." relative="path">
  Go up one path segment
</Link>

---

Accessing Location State

Read state passed during navigation:

import { useLocation } from "react-router";

function Checkout() {
  const location = useLocation();
  const { from } = location.state || {};

  return (
    <div>
      <h1>Checkout</h1>
      {from && <Link to={from}>Go back</Link>}
    </div>
  );
}

---

ScrollRestoration

Add <ScrollRestoration /> to handle scroll position automatically:

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

function Root() {
  return (
    <div>
      <nav>...</nav>
      <main>
        <Outlet />
      </main>
      <ScrollRestoration />
    </div>
  );
}

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    children: [
      // ...routes
    ],
  },
]);

Prevent scroll reset on specific links:

<Link to="/products" preventScrollReset>
  Products
</Link>

---

useSearchParams

Access and modify URL search params:

import { useSearchParams } from "react-router";

function FilterPanel() {
  const [searchParams, setSearchParams] = useSearchParams();
  const category = searchParams.get("category") ?? "all";

  // ⚠️ For form submissions, prefer <Form method="get"> instead
  function handleChange(newCategory: string) {
    setSearchParams({ category: newCategory });
  }

  return (
    <select value={category} onChange={(e) => handleChange(e.target.value)}>
      <option value="all">All</option>
      <option value="electronics">Electronics</option>
      <option value="clothing">Clothing</option>
    </select>
  );
}

---

Complete Navigation Example

import {
  createBrowserRouter,
  RouterProvider,
  Link,
  NavLink,
  Outlet,
  ScrollRestoration,
  useNavigate,
  redirect,
} from "react-router";

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    children: [
      { index: true, Component: Home },
      { path: "about", Component: About },
      {
        path: "dashboard",
        loader: async () => {
          const user = await getUser();
          if (!user) throw redirect("/login");
          return user;
        },
        Component: Dashboard,
      },
    ],
  },
]);

function Root() {
  return (
    <div>
      <nav>
        <NavLink to="/" end className={({ isActive }) => isActive ? "active" : ""}>
          Home
        </NavLink>
        <NavLink to="/about" className={({ isActive }) => isActive ? "active" : ""}>
          About
        </NavLink>
        <NavLink to="/dashboard" className={({ isActive, isPending }) =>
          isPending ? "pending" : isActive ? "active" : ""
        }>
          Dashboard
        </NavLink>
      </nav>
      <main>
        <Outlet />
      </main>
      <ScrollRestoration />
    </div>
  );
}

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

  async function handleLogout() {
    await logout();
    navigate("/login", { replace: true });
  }

  return (
    <div>
      <h1>Dashboard</h1>
      <button onClick={handleLogout}>Logout</button>
    </div>
  );
}

---

See Also

• pending-ui.md - NavLink pending states
• actions.md - Form navigation patterns
• React Router Navigation Documentation

Pending UI and Optimistic Updates

Key principle: Show expected results immediately using fetcher.formData, then let React Router sync with the server.

Quick Reference

For mutation patterns (when to use Form vs useFetcher), see actions.md.

---

useNavigation

Track global navigation state:

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

function Root() {
  const navigation = useNavigation();
  const isNavigating = Boolean(navigation.location);

  return (
    <div className={isNavigating ? "loading" : ""}>
      {isNavigating && <GlobalSpinner />}
      <Outlet />
    </div>
  );
}

Navigation States

• navigation.state - "idle", "loading", or "submitting"
• navigation.location - The location being navigated to (if any)
• navigation.formData - Form data being submitted (if any)
• navigation.formMethod - HTTP method of the submission

const navigation = useNavigation();

// Check if navigating
const isNavigating = navigation.state !== "idle";

// Check if submitting a form
const isSubmitting = navigation.state === "submitting";

// Check if loading after submission
const isLoading = navigation.state === "loading";

---

NavLink Pending State

Show pending state on the specific link being clicked:

import { NavLink } from "react-router";

function Nav() {
  return (
    <NavLink to="/dashboard">
      {({ isPending }) => <span>Dashboard {isPending && <Spinner />}</span>}
    </NavLink>
  );
}

Or use className:

<NavLink
  to="/dashboard"
  className={({ isPending }) => (isPending ? "pending" : "")}
>
  Dashboard
</NavLink>

---

useFetcher for Local State

Each fetcher tracks its own state independently:

import { useFetcher } from "react-router";

function LikeButton({ postId, liked }) {
  const fetcher = useFetcher();

  // Show pending state while submitting
  const isPending = fetcher.state !== "idle";

  return (
    <fetcher.Form method="post" action={`/posts/${postId}/like`}>
      <button disabled={isPending}>
        {isPending ? "..." : liked ? "Unlike" : "Like"}
      </button>
    </fetcher.Form>
  );
}

Fetcher States

• fetcher.state - "idle", "submitting", or "loading"
• fetcher.data - Data returned from the action/loader
• fetcher.formData - Form data being submitted

---

Optimistic UI with useFetcher (Recommended Pattern)

This is the standard pattern for mutations. Show the expected result immediately using fetcher.formData:

import { useFetcher } from "react-router";

function FavoriteButton({ itemId, isFavorite }) {
  const fetcher = useFetcher();

  // Optimistic: use pending form data, fallback to server state
  const optimistic = fetcher.formData
    ? fetcher.formData.get("favorite") === "true"
    : isFavorite;

  return (
    <fetcher.Form method="post" action={`/items/${itemId}/favorite`}>
      <input type="hidden" name="favorite" value={String(!optimistic)} />
      <button>{optimistic ? "★" : "☆"}</button>
    </fetcher.Form>
  );
}

Complete Optimistic UI Example

import { useFetcher } from "react-router";

function RatingStars({ itemId, currentRating }) {
  const fetcher = useFetcher();

  // 1. Check if we're submitting - use the pending value
  // 2. Otherwise use the server value
  const displayRating = fetcher.formData
    ? Number(fetcher.formData.get("rating"))
    : currentRating;

  const isSubmitting = fetcher.state !== "idle";

  return (
    <fetcher.Form method="post" action={`/items/${itemId}/rate`}>
      <div style={{ opacity: isSubmitting ? 0.5 : 1 }}>
        {[1, 2, 3, 4, 5].map((star) => (
          <button key={star} type="submit" name="rating" value={star}>
            {star <= displayRating ? "★" : "☆"}
          </button>
        ))}
      </div>
    </fetcher.Form>
  );
}

Why fetcher.formData?

• Instant feedback - UI updates immediately on click
• No loading spinners needed - the optimistic state IS the loading state
• Automatic rollback - if the action fails, loaders revalidate and reset to server state

---

Optimistic UI with useNavigation

For form submissions that navigate (using <Form> instead of useFetcher):

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

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

  // Get optimistic value from submission
  const optimisticTitle = navigation.formData?.get("title");
  const isSubmitting = navigation.state === "submitting";

  return (
    <Form method="post">
      <input type="text" name="title" />
      <button disabled={isSubmitting}>
        {isSubmitting ? "Creating..." : "Create"}
      </button>

      {optimisticTitle && <p>Creating "{optimisticTitle}"...</p>}
    </Form>
  );
}

---

Disabling During Submission

Prevent double submissions:

function ContactForm() {
  const navigation = useNavigation();
  const isSubmitting = navigation.state === "submitting";

  return (
    <Form method="post">
      <input type="text" name="message" disabled={isSubmitting} />
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Sending..." : "Send"}
      </button>
    </Form>
  );
}

With useFetcher:

function CommentForm() {
  const fetcher = useFetcher();
  const isSubmitting = fetcher.state === "submitting";

  return (
    <fetcher.Form method="post">
      <textarea name="comment" disabled={isSubmitting} />
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Posting..." : "Post Comment"}
      </button>
    </fetcher.Form>
  );
}

---

Skeleton Loading Patterns

Show skeletons while data loads during navigation:

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

function Root() {
  const navigation = useNavigation();
  const isLoading = navigation.state === "loading";

  return (
    <div>
      <nav>...</nav>
      <main>{isLoading ? <PageSkeleton /> : <Outlet />}</main>
    </div>
  );
}

Route-specific Skeletons

function Root() {
  const navigation = useNavigation();
  const isLoading = navigation.state === "loading";
  const nextPath = navigation.location?.pathname;

  return (
    <div>
      <nav>...</nav>
      <main>
        {isLoading && nextPath?.startsWith("/dashboard") ? (
          <DashboardSkeleton />
        ) : isLoading ? (
          <GenericSkeleton />
        ) : (
          <Outlet />
        )}
      </main>
    </div>
  );
}

---

Busy Indicators with CSS

function Root() {
  const navigation = useNavigation();
  const isNavigating = navigation.state !== "idle";

  return (
    <div style={{ opacity: isNavigating ? 0.5 : 1 }}>
      <Outlet />
    </div>
  );
}

---

Progress Indicators

Show progress during slow navigations:

import { useNavigation } from "react-router";

function GlobalProgress() {
  const navigation = useNavigation();
  const isNavigating = navigation.state !== "idle";

  if (!isNavigating) return null;

  return <ProgressBar />;
}

function Root() {
  return (
    <div>
      <GlobalProgress />
      <nav>...</nav>
      <Outlet />
    </div>
  );
}

---

Complete Example

import {
  createBrowserRouter,
  RouterProvider,
  NavLink,
  Outlet,
  useNavigation,
  useFetcher,
} from "react-router";

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    children: [
      { index: true, Component: Home },
      {
        path: "items/:itemId",
        loader: async ({ params }) => fetchItem(params.itemId),
        action: async ({ request, params }) => {
          const formData = await request.formData();
          return toggleFavorite(
            params.itemId,
            formData.get("favorite") === "true",
          );
        },
        Component: Item,
      },
    ],
  },
]);

function Root() {
  const navigation = useNavigation();
  const isNavigating = navigation.state !== "idle";

  return (
    <div style={{ opacity: isNavigating ? 0.5 : 1 }}>
      <nav>
        <NavLink
          to="/"
          className={({ isPending }) => (isPending ? "pending" : "")}
        >
          Home
        </NavLink>
      </nav>
      {isNavigating && <GlobalSpinner />}
      <Outlet />
    </div>
  );
}

function Item() {
  const { item } = useLoaderData();
  const fetcher = useFetcher();

  // Optimistic UI
  const isFavorite = fetcher.formData
    ? fetcher.formData.get("favorite") === "true"
    : item.isFavorite;

  return (
    <div>
      <h1>{item.name}</h1>
      <fetcher.Form method="post">
        <input type="hidden" name="favorite" value={String(!isFavorite)} />
        <button>{isFavorite ? "★ Favorited" : "☆ Add to Favorites"}</button>
      </fetcher.Form>
    </div>
  );
}

---

See Also

• actions.md - Form handling and useFetcher patterns
• navigation.md - NavLink and navigation
• React Router Pending UI Documentation

Route Object

Route objects define the behavior of each route in your application.

Properties Quick Reference

Component

The React component to render when the route matches:

const router = createBrowserRouter([
  {
    path: "/about",
    Component: About,
  },
]);

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

Use useLoaderData() and useActionData() hooks inside the component to access data.

loader

Function that loads data before the component renders:

const router = createBrowserRouter([
  {
    path: "/teams/:teamId",
    loader: async ({ params, request }) => {
      return fetchTeam(params.teamId);
    },
    Component: Team,
  },
]);

See data-loading.md for complete patterns.

action

Function that handles form submissions and mutations:

const router = createBrowserRouter([
  {
    path: "/projects/new",
    action: async ({ request }) => {
      const formData = await request.formData();
      const project = await createProject(formData);
      return redirect(`/projects/${project.id}`);
    },
    Component: NewProject,
  },
]);

See actions.md for complete patterns.

children

Array of nested route objects:

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    children: [
      { index: true, Component: Home },
      { path: "about", Component: About },
      {
        path: "dashboard",
        Component: Dashboard,
        children: [
          { index: true, Component: DashboardHome },
          { path: "settings", Component: Settings },
        ],
      },
    ],
  },
]);

index

Marks the route as an index route (renders at parent's URL):

{
  path: "/dashboard",
  Component: Dashboard,
  children: [
    { index: true, Component: DashboardHome }, // Renders at /dashboard
    { path: "settings", Component: Settings }, // Renders at /dashboard/settings
  ],
}

ErrorBoundary

Component to render when errors occur in the route:

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

const router = createBrowserRouter([
  {
    path: "/teams/:teamId",
    loader: async ({ params }) => {
      const team = await fetchTeam(params.teamId);
      if (!team) {
        throw new Response("Not Found", { status: 404 });
      }
      return team;
    },
    Component: Team,
    ErrorBoundary: TeamErrorBoundary,
  },
]);

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

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

  if (error instanceof Error) {
    return <h1>Error: {error.message}</h1>;
  }

  return <h1>Unknown Error</h1>;
}

lazy

Code-split route modules for better performance:

const router = createBrowserRouter([
  {
    path: "/dashboard",
    lazy: async () => {
      const { Dashboard, loader } = await import("./routes/dashboard");
      return { Component: Dashboard, loader };
    },
  },
]);

The lazy function can return any route properties except path and children:

lazy: async () => ({
  Component: Dashboard,
  loader: dashboardLoader,
  action: dashboardAction,
  ErrorBoundary: DashboardError,
});

shouldRevalidate

Control when the loader re-runs after navigation:

const router = createBrowserRouter([
  {
    path: "/products",
    loader: productsLoader,
    shouldRevalidate: ({
      currentUrl,
      nextUrl,
      formMethod,
      defaultShouldRevalidate,
    }) => {
      // Don't revalidate on search param changes only
      if (currentUrl.pathname === nextUrl.pathname) {
        return false;
      }
      return defaultShouldRevalidate;
    },
    Component: Products,
  },
]);

ShouldRevalidate Arguments

• currentUrl - The current URL
• nextUrl - The URL being navigated to
• formMethod - HTTP method if triggered by form submission
• formAction - Form action URL if triggered by form
• formData - Form data if triggered by form submission
• defaultShouldRevalidate - React Router's default decision

middleware (v7.9.0+)

Array of functions that run before loaders and actions:

import { unstable_MiddlewareContext as MiddlewareContext } from "react-router";

const userContext = new MiddlewareContext<User>();

const router = createBrowserRouter([
  {
    path: "/dashboard",
    middleware: [
      async ({ request, context }, next) => {
        const user = await getUser(request);
        if (!user) {
          throw redirect("/login");
        }
        context.set(userContext, user);
        return next();
      },
    ],
    loader: async ({ context }) => {
      const user = context.get(userContext);
      return { user };
    },
    Component: Dashboard,
  },
]);

handle

Custom metadata accessible via useMatches():

const router = createBrowserRouter([
  {
    path: "/dashboard",
    Component: Dashboard,
    handle: {
      breadcrumb: "Dashboard",
      permissions: ["admin"],
    },
  },
]);

// Access in any component
function Breadcrumbs() {
  const matches = useMatches();
  const crumbs = matches
    .filter((m) => m.handle?.breadcrumb)
    .map((m) => m.handle.breadcrumb);
  return <nav>{crumbs.join(" > ")}</nav>;
}

Complete Example

import {
  createBrowserRouter,
  RouterProvider,
  redirect,
  isRouteErrorResponse,
  useRouteError,
  useLoaderData,
} from "react-router";

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    ErrorBoundary: RootErrorBoundary,
    children: [
      { index: true, Component: Home },
      {
        path: "teams/:teamId",
        loader: async ({ params }) => {
          const team = await fetchTeam(params.teamId);
          if (!team) {
            throw new Response("Not Found", { status: 404 });
          }
          return team;
        },
        action: async ({ request, params }) => {
          const formData = await request.formData();
          await updateTeam(params.teamId, formData);
          return { success: true };
        },
        Component: Team,
        ErrorBoundary: TeamError,
        handle: { breadcrumb: "Team" },
      },
    ],
  },
]);

ReactDOM.createRoot(document.getElementById("root")).render(
  <RouterProvider router={router} />,
);

See Also

• routing.md - Route configuration patterns
• data-loading.md - Loader patterns
• actions.md - Action patterns
• React Router Route Object Documentation

Routing

Routes are configured as JavaScript objects and passed to createBrowserRouter.

Basic Setup

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

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    children: [
      { index: true, Component: Home },
      { path: "about", Component: About },
      {
        path: "dashboard",
        Component: Dashboard,
        children: [
          { index: true, Component: DashboardHome },
          { path: "settings", Component: Settings },
        ],
      },
    ],
  },
]);

ReactDOM.createRoot(document.getElementById("root")).render(
  <RouterProvider router={router} />
);

Route Object Properties

See route-object.md for all properties.

Nested Routes

Child routes render inside the parent's <Outlet />:

import { Outlet } from "react-router";

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    children: [
      { path: "teams", Component: Teams },
      { path: "projects", Component: Projects },
    ],
  },
]);

function Root() {
  return (
    <div>
      <nav>
        <Link to="/teams">Teams</Link>
        <Link to="/projects">Projects</Link>
      </nav>
      <main>
        <Outlet />
      </main>
    </div>
  );
}

Parent path is automatically included in children: /teams and /projects.

Deeply Nested Routes

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    children: [
      {
        path: "dashboard",
        Component: Dashboard,
        children: [
          { index: true, Component: DashboardHome },
          { path: "settings", Component: Settings },
          { path: "profile", Component: Profile },
        ],
      },
    ],
  },
]);

Creates: /dashboard, /dashboard/settings, /dashboard/profile.

Layout Routes

Layout routes have no path - they only provide UI wrapper via <Outlet />:

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    children: [
      {
        // No path - this is a layout route
        Component: AuthLayout,
        children: [
          { path: "login", Component: Login },
          { path: "register", Component: Register },
        ],
      },
    ],
  },
]);

function AuthLayout() {
  return (
    <div className="auth-container">
      <Outlet />
    </div>
  );
}

Both /login and /register render inside AuthLayout.

Index Routes

Index routes render at the parent's URL (default child):

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    children: [
      { index: true, Component: Home }, // Renders at /
      {
        path: "dashboard",
        Component: Dashboard,
        children: [
          { index: true, Component: DashboardHome }, // Renders at /dashboard
          { path: "settings", Component: Settings }, // Renders at /dashboard/settings
        ],
      },
    ],
  },
]);

Index routes cannot have children.

Dynamic Segments

Segments starting with : are dynamic and available via useParams or params:

const router = createBrowserRouter([
  {
    path: "/teams/:teamId",
    loader: async ({ params }) => {
      return fetchTeam(params.teamId);
    },
    Component: Team,
  },
]);

function Team() {
  const { teamId } = useParams();
  const data = useLoaderData();
  return <h1>Team {teamId}: {data.name}</h1>;
}

Multiple dynamic segments:

{ path: "c/:categoryId/p/:productId", Component: Product }
// params: { categoryId: string; productId: string }

Optional Segments

Add ? to make a segment optional:

{ path: ":lang?/categories", Component: Categories }
// Matches /categories and /en/categories

{ path: "users/:userId/edit?", Component: User }
// Matches /users/123 and /users/123/edit

Splats (Catch-All)

Match any remaining path with *:

const router = createBrowserRouter([
  {
    path: "/files/*",
    loader: async ({ params }) => {
      const filePath = params["*"]; // e.g., "docs/intro.md"
      return getFile(filePath);
    },
    Component: FileBrowser,
  },
]);

404 Catch-All

const router = createBrowserRouter([
  {
    path: "/",
    Component: Root,
    children: [
      // ... other routes
      {
        path: "*",
        Component: NotFound,
      },
    ],
  },
]);

function NotFound() {
  return <h1>Page not found</h1>;
}

Anti-Pattern: Flat Routes

// ❌ DON'T: Flat structure with no shared layouts
const router = createBrowserRouter([
  { path: "/dashboard", Component: Dashboard },
  { path: "/dashboard/settings", Component: DashboardSettings },
  { path: "/dashboard/profile", Component: DashboardProfile },
]);

// ✅ DO: Use nested routes with shared layout
const router = createBrowserRouter([
  {
    path: "/dashboard",
    Component: DashboardLayout,
    children: [
      { index: true, Component: Dashboard },
      { path: "settings", Component: Settings },
      { path: "profile", Component: Profile },
    ],
  },
]);

See Also

• route-object.md - All route object properties
• React Router Routing Documentation

Server-Side Rendering

SSR with data mode requires manual setup using createStaticHandler on the server and hydration with createBrowserRouter on the client. Use this when you want SSR without the framework's Vite plugin.

When to Use

• Server-side rendering with data mode (without the framework Vite plugin)
• Custom server setups (Express, Fastify, etc.)
• Need to run loaders/actions on the server

Route Configuration

Extract routes to a shared file used by both server and client:

// routes.tsx
import { Home } from "./pages/Home";
import { About } from "./pages/About";
import { Team } from "./pages/Team";

export const routes = [
  {
    path: "/",
    Component: Root,
    children: [
      { index: true, Component: Home },
      { path: "about", Component: About },
      {
        path: "teams/:teamId",
        loader: async ({ params }) => {
          return fetchTeam(params.teamId);
        },
        Component: Team,
      },
    ],
  },
];

Server-Side Rendering

Use createStaticHandler to create a handler that runs loaders and actions on the server:

// server.tsx
import { createStaticHandler, createStaticRouter, StaticRouterProvider } from "react-router";
import { renderToString } from "react-dom/server";
import { routes } from "./routes";

export async function render(request: Request): Promise<Response> {
  // Create handler that can run loaders/actions
  const handler = createStaticHandler(routes);

  // Execute loaders for the matched routes
  const context = await handler.query(request);

  // Handle redirects (query returns a Response for redirects)
  if (context instanceof Response) {
    return context;
  }

  // Create static router with the context from loaders
  const router = createStaticRouter(handler.dataRoutes, context);

  // Render the app to HTML
  const html = renderToString(
    <StaticRouterProvider router={router} context={context} />
  );

  return new Response(renderFullDocument(html), {
    headers: { "Content-Type": "text/html" },
  });
}

Handle Redirects

The handler.query() method returns a Response when a loader or action redirects:

const context = await handler.query(request);

// Check if it's a redirect response
if (context instanceof Response) {
  // Return the redirect response directly
  return context;
}

// Otherwise, context contains the routing data
const router = createStaticRouter(handler.dataRoutes, context);

HTML Template

Include CSS in a <link> tag to avoid flash of unstyled content:

function renderFullDocument(appHtml: string): string {
  return `<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>My App</title>
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <div id="root">${appHtml}</div>
    <script type="module" src="/client.tsx"></script>
  </body>
</html>`;
}

Client Hydration

Use createBrowserRouter with the same routes and hydrate with hydrateRoot:

// client.tsx
import { createBrowserRouter, RouterProvider } from "react-router";
import { hydrateRoot } from "react-dom/client";
import { routes } from "./routes";

const router = createBrowserRouter(routes);

hydrateRoot(
  document.getElementById("root")!,
  <RouterProvider router={router} />
);

The browser router automatically picks up the data that was serialized from the server.

Complete Example

Shared Routes

// routes.tsx
import { Root } from "./components/Root";
import { Home } from "./pages/Home";
import { Team } from "./pages/Team";
import { fetchTeam } from "./api";

export const routes = [
  {
    path: "/",
    Component: Root,
    children: [
      { index: true, Component: Home },
      {
        path: "teams/:teamId",
        loader: async ({ params }) => {
          return fetchTeam(params.teamId);
        },
        Component: Team,
      },
    ],
  },
];

Server Entry

// server.tsx
import {
  createStaticHandler,
  createStaticRouter,
  StaticRouterProvider,
} from "react-router";
import { renderToString } from "react-dom/server";
import { routes } from "./routes";

export async function handleRequest(request: Request): Promise<Response> {
  const handler = createStaticHandler(routes);
  const context = await handler.query(request);

  // Handle redirects
  if (context instanceof Response) {
    return context;
  }

  const router = createStaticRouter(handler.dataRoutes, context);

  const appHtml = renderToString(
    <StaticRouterProvider router={router} context={context} />
  );

  const html = `<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <div id="root">${appHtml}</div>
    <script type="module" src="/client.tsx"></script>
  </body>
</html>`;

  return new Response(html, {
    headers: { "Content-Type": "text/html" },
  });
}

Client Entry

// client.tsx
import { createBrowserRouter, RouterProvider } from "react-router";
import { hydrateRoot } from "react-dom/client";
import { routes } from "./routes";

const router = createBrowserRouter(routes);

hydrateRoot(
  document.getElementById("root")!,
  <RouterProvider router={router} />
);

CSS Considerations

Always include CSS as a <link> tag in the HTML template, not just via JavaScript imports:

// ❌ DON'T: Only import CSS in JavaScript
// This causes flash of unstyled content on initial load
import "./styles.css";

// ✅ DO: Include CSS in the HTML template
<link rel="stylesheet" href="/styles.css" />

JavaScript-imported CSS won't be available until the JS loads and executes, causing a flash of unstyled content (FOUC) on the initial server-rendered page.

API Reference

See Also

• routing.md - Route configuration
• data-loading.md - Loader patterns
• React Router SSR Documentation