# React Router v7 - Comprehensive Reference Guide ## Overview React Router is a modern routing library that provides flexible client-side and server-side routing for React applications. It offers two primary modes of operation: Framework Mode and Data Mode, with first-class TypeScript support through automatic type generation. ## Installation and Setup ### Basic Installation ```bash npm install react-router ``` ### TypeScript Configuration React Router generates type-specific files for each route. Configure your `tsconfig.json`: ```json { "include": [".react-router/types/**/*"], "compilerOptions": { "rootDirs": [".", "./.react-router/types"] } } ``` Add `.react-router/` to `.gitignore`: ```txt .react-router/ ``` ### Extending AppLoadContext Define your app's context type in a `.ts` or `.d.ts` file: ```typescript import "react-router"; declare module "react-router" { interface AppLoadContext { // add context properties here apiClient?: APIClient; userId?: string; } } ``` ## Route Definition Patterns ### Basic Route Configuration Routes are defined as objects passed to `createBrowserRouter`: ```tsx import { createBrowserRouter } from "react-router"; const router = createBrowserRouter([ { path: "/", Component: Root }, { path: "/about", Component: About }, ]); ``` ### Nested Routes Child routes are rendered through an `` in the parent component: ```tsx createBrowserRouter([ { path: "/dashboard", Component: Dashboard, children: [ { index: true, Component: DashboardHome }, { path: "settings", Component: Settings }, ], }, ]); function Dashboard() { return ( ); } ``` ### Layout Routes (No Path) Create layout containers without adding URL segments: ```tsx createBrowserRouter([ { // no path - just a layout Component: MarketingLayout, children: [ { index: true, Component: Home }, { path: "contact", Component: Contact }, ], }, ]); ``` ### Index Routes Define default routes at a path: ```tsx createBrowserRouter([ { path: "/", Component: Root, children: [ { index: true, Component: Home }, // renders at "/" { path: "about", Component: About }, ], }, ]); ``` ### Dynamic Segments Use colons to define dynamic parameters: ```tsx { path: "teams/:teamId", loader: async ({ params }) => { return await fetchTeam(params.teamId); }, Component: Team, } ``` Multiple dynamic segments: ```tsx { path: "posts/:postId/comments/:commentId", // params.postId and params.commentId available } ``` ### Optional Segments ```tsx { path: ":lang?/categories" // lang is optional } ``` ### Splat Routes (Catchall) ```tsx { path: "files/*", loader: async ({ params }) => { const splat = params["*"]; // remaining URL after "files/" }, } ``` ## TypeScript Typing ### Route Type Imports In Framework Mode, import route-specific types from the generated `+types` directory: ```tsx import type { Route } from "./+types/product"; export async function loader({ params }: Route.LoaderArgs) { // params is typed as { id: string } return { planet: `world #${params.id}` }; } export default function Product({ loaderData, // typed from loader }: Route.ComponentProps) { return

{loaderData.planet}

; } ``` ### Generated Types React Router generates these types for each route: - `Route.LoaderArgs` - Loader function arguments - `Route.ClientLoaderArgs` - Client loader arguments - `Route.ActionArgs` - Action function arguments - `Route.ClientActionArgs` - Client action arguments - `Route.ComponentProps` - Props for default export - `Route.ErrorBoundaryProps` - Props for ErrorBoundary - `Route.HydrateFallbackProps` - Props for HydrateFallback ### Manual Loader Data Typing In Data Mode, type loader data manually: ```tsx export async function loader() { return { invoices: await getInvoices() }; } export default function Invoices() { const data = useLoaderData(); // data is typed as { invoices: ... } } ``` ### Action Data Typing ```tsx export async function action({ request }: Route.ActionArgs) { const formData = await request.formData(); return { message: `Hello, ${formData.get("name")}` }; } export default function Form() { const actionData = useActionData(); // actionData is typed correctly } ``` ## Data Loading with Loaders ### Basic Loader Pattern Loaders provide data to route components before rendering: ```tsx createBrowserRouter([ { path: "/posts/:postId", loader: async ({ params }) => { const post = await fetchPost(params.postId); return { post }; }, Component: Post, }, ]); function Post() { const { post } = useLoaderData(); return

{post.title}

; } ``` ### Loader Arguments ```tsx type LoaderFunctionArgs = { params: Params; // URL parameters request: Request; // fetch API Request context?: AppLoadContext; // shared context }; ``` ### Error Handling in Loaders Throw errors with `data()` function for client-side error boundaries: ```tsx import { data } from "react-router"; export async function loader({ params }: Route.LoaderArgs) { const record = await fakeDb.getRecord(params.id); if (!record) { throw data("Record Not Found", { status: 404 }); } return record; } ``` ### Revalidation Control Control when loaders rerun: ```tsx export const shouldRevalidate: ShouldRevalidateFunctionArgs = (args) => { // Return true to revalidate, false to skip // Default: true when params change or after successful action return true; }; ``` ### Lazy Loading Load components and loaders on-demand: ```tsx { path: "/app", lazy: async () => { const { Component, loader } = await import("./app"); return { Component, loader }; }, } ``` ## Actions and Form Handling ### Basic Action Pattern Actions handle form submissions and mutations: ```tsx createBrowserRouter([ { path: "/projects", action: async ({ request }) => { const formData = await request.formData(); const title = formData.get("title"); const project = await createProject({ title }); return project; // data available via useActionData }, Component: Projects, }, ]); ``` ### Form Submission Methods #### Using `` Component Causes navigation and adds history entry: ```tsx import { Form } from "react-router"; export default function CreateEvent() { return ( Create ); } ``` #### Using `useSubmit` Hook Imperative form submission: ```tsx import { useSubmit } from "react-router"; export default function Timer() { const submit = useSubmit(); const handleTimeout = () => { submit( { quizTimedOut: true }, { action: "/end-quiz", method: "post" } ); }; return ; } ``` #### Using `useFetcher` Hook Submit without navigation (no history entry): ```tsx import { useFetcher } from "react-router"; export default function Task() { const fetcher = useFetcher(); return ( Save ); } ``` ### Form Validation Return errors with non-2xx status codes: ```tsx export async function action({ request }: Route.ActionArgs) { const formData = await request.formData(); const email = String(formData.get("email")); const errors: Record = {}; if (!email.includes("@")) { errors.email = "Invalid email"; } if (Object.keys(errors).length > 0) { return data({ errors }, { status: 400 }); // Don't revalidate } await createUser({ email }); return redirect("/dashboard"); } export default function Signup() { const fetcher = useFetcher(); const errors = fetcher.data?.errors; return ( {errors?.email && {errors.email}} Sign Up ); } ``` ### Accessing Action Data ```tsx import { useActionData } from "react-router"; export default function Project() { const actionData = useActionData(); return ( ); } ``` ## Navigation Patterns ### Link Component For client-side navigation without active styling: ```tsx import { Link } from "react-router"; Dashboard Search ``` ### NavLink Component For navigation with active/pending states: ```tsx import { NavLink } from "react-router"; {({ isActive, isPending }) => ( Messages )} ``` ### Programmatic Navigation ```tsx import { useNavigate } from "react-router"; export default function LogoutButton() { const navigate = useNavigate(); return ( navigate("/")}> Go Home ); } ``` ### Navigate Options ```tsx navigate("/path", { replace: true, // Don't add to history state: { from: "/" }, // Pass state relative: "route", // Or "path" preventScrollReset: true, // Don't scroll to top viewTransition: true, // Enable view transition }); navigate(-1); // Go back navigate(1); // Go forward ``` ### Redirect in Loaders/Actions ```tsx import { redirect } from "react-router"; export async function loader({ request }: Route.LoaderArgs) { const user = await getUser(request); if (!user) { return redirect("/login"); } return { user }; } export async function action() { const project = await createProject(); return redirect(`/projects/${project.id}`); } ``` ## URL Parameters and Search Params ### Route Parameters Access dynamic route parameters: ```tsx import { useParams } from "react-router"; export default function Post() { const params = useParams(); // params.postId is typed as string return

Post: {params.postId}

; } ``` ### Search Parameters Handle query strings: ```tsx import { useSearchParams } from "react-router"; export default function Search() { const [searchParams, setSearchParams] = useSearchParams(); const query = searchParams.get("q"); const page = searchParams.get("page") || "1"; return ( ); } ``` ### Setting Search Params ```tsx // String setSearchParams("?tab=1"); // Object setSearchParams({ tab: "1" }); // Multiple values setSearchParams({ brand: ["nike", "reebok"] }); // Callback setSearchParams((prev) => { prev.set("tab", "2"); return prev; }); ``` ## Error Handling ### Framework Mode Error Boundaries ```tsx import { Route } from "./+types/root"; import { isRouteErrorResponse } from "react-router"; export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) { if (isRouteErrorResponse(error)) { return ( ); } if (error instanceof Error) { return ( ); } return

Unknown Error

; } ``` ### Data Mode Error Boundaries ```tsx import { useRouteError, isRouteErrorResponse } from "react-router"; function RootErrorBoundary() { const error = useRouteError(); if (isRouteErrorResponse(error)) { return ( ); } return

Error

; } createBrowserRouter([ { path: "/", Component: Root, ErrorBoundary: RootErrorBoundary, }, ]); ``` ### Throwing Errors Unintentional errors are caught: ```tsx export async function loader() { return undefined(); // Error thrown and caught } ``` Intentional errors with status codes: ```tsx import { data } from "react-router"; export async function loader({ params }: Route.LoaderArgs) { const post = await getPost(params.id); if (!post) { throw data("Not Found", { status: 404 }); } return post; } ``` ## Advanced Hooks ### useLoaderData Get data from the route's loader: ```tsx export default function Component() { const data = useLoaderData(); // fully typed } ``` ### useActionData Get data from the last action submission: ```tsx export default function Form() { const actionData = useActionData(); return actionData ?

{actionData.message}

: null; } ``` ### useFetcher Independent data submission without navigation: ```tsx const fetcher = useFetcher(); fetcher.state; // "idle" | "loading" | "submitting" fetcher.data; // data from action/loader fetcher.Form; // component for forms fetcher.load(path); // load data fetcher.submit(data, options); // submit data fetcher.reset(); // reset state ``` Keyed fetchers (access from other components): ```tsx const fetcher = useFetcher({ key: "my-fetcher" }); ``` ### useMatches Get all active route matches: ```tsx const matches = useMatches(); // Array of: { route, pathname, params, data, handle } matches.forEach(match => { console.log(match.data); // Loader data console.log(match.handle); // Route handle metadata }); ``` ### useLocation Get current location: ```tsx const location = useLocation(); // { // pathname: "/posts/123", // search: "?tab=1", // hash: "#section", // state: { from: "/" } // } ``` ### useNavigation Track navigation state: ```tsx const navigation = useNavigation(); navigation.state; // "idle" | "loading" | "submitting" navigation.location; // new location during navigation navigation.formData; // form data being submitted ``` ## Advanced Route Features ### Route Handle Property Attach metadata to routes for use in ancestor components: ```tsx // Route definition export const handle = { breadcrumb: () => Posts, icon: "?", }; // Access in ancestor function Root() { const matches = useMatches(); return (

{matches .filter(m => m.handle?.breadcrumb) .map(m => m.handle.breadcrumb())}

); } ``` ### Middleware Run code before/after navigations: ```tsx export async function middleware({ request }, next) { console.log(`Starting: ${request.url}`); await next(); console.log("Complete"); } createBrowserRouter([ { path: "/", middleware: [middleware], loader: rootLoader, Component: Root, }, ]); ``` ### Outlet Component Render child routes: ```tsx import { Outlet } from "react-router"; function Layout() { return ( ); } ``` ### OutletContext Pass data to child routes via Outlet: ```tsx // Parent function Parent() { return ; } // Child import { useOutletContext } from "react-router"; function Child() { const { user } = useOutletContext(); return

{user.name}

; } ``` ## Comparison with TanStack Router ### Type Safety Similarities Both React Router v7 and TanStack Router offer first-class TypeScript support: | Feature | React Router v7 | TanStack Router | |---------|-----------------|-----------------| | Route type generation | ✓ Automatic `.react-router/types/` | ✓ Automatic | | Param typing | ✓ Auto-inferred from path | ✓ Auto-inferred | | Loader data typing | ✓ Via `Route.LoaderArgs` | ✓ Via `loader()` return type | | Action typing | ✓ Via `Route.ActionArgs` | ✓ Via `action()` return type | | Search params typing | ✓ Manual with `useSearchParams` | ✓ Route-level definition | | Redirect typing | ✓ Standard function | ✓ Standard function | ### Key Differences **Type Definition Level:** - React Router: File-based type generation (`.d.ts` files) - TanStack Router: Route-level type registration **Search Params:** - React Router: Runtime `URLSearchParams` API - TanStack Router: Compile-time schema validation **Nested Route Typing:** - React Router: Inherited from parent context - TanStack Router: Explicit inheritance patterns **Error Typing:** - React Router: `isRouteErrorResponse()` utility - TanStack Router: Built-in discriminated unions **Learning Curve:** - React Router: Familiar to those migrating from v6 - TanStack Router: More opinionated, explicit type patterns ## Best Practices ### 1. Type Your Routes Consistently ```tsx // In Framework Mode, always use the generated types import type { Route } from "./+types/my-route"; export async function loader({ params }: Route.LoaderArgs) { // params is typed } export default function Component({ loaderData }: Route.ComponentProps) { // loaderData is typed } ``` ### 2. Use Forms for Navigation-Causing Mutations ```tsx // Good: Uses for main app actions Create ``` ### 3. Use Fetchers for Non-Navigation Mutations ```tsx // Good: Uses fetcher for secondary updates const fetcher = useFetcher(); Update ``` ### 4. Handle Validation Errors Properly ```tsx // Return with 4xx status to prevent revalidation if (validationFailed) { return data({ errors }, { status: 400 }); } ``` ### 5. Use `redirect()` in Loaders/Actions ```tsx // Prefer redirect in loaders/actions if (!user) { return redirect("/login"); } // Over useNavigate in components const navigate = useNavigate(); // Reserve for rare cases ``` ### 6. Leverage `useMatches()` for Layout Data ```tsx // Access parent route data in nested components const matches = useMatches(); const parentData = matches[matches.length - 2]?.data; ``` ## Router Creation ### Data Mode (createBrowserRouter) ```tsx import { createBrowserRouter, RouterProvider } from "react-router"; const router = createBrowserRouter([ { path: "/", Component: Home }, { path: "/about", Component: About }, ]); export default function App() { return ; } ``` ### Framework Mode Setup Use the framework convention with `routes.ts`: ```ts filename=app/routes.ts import { route, type RouteConfig } from "@react-router/dev/routes"; export default [ route("/", "./routes/index.tsx"), route("about", "./routes/about.tsx"), route("posts/:id", "./routes/post.tsx"), ] satisfies RouteConfig; ``` ### Router Options ```tsx const router = createBrowserRouter(routes, { basename: "/app", // URL base path future: { v7_... }, // Future flags hydrationData: serverData, // SSR hydration dataStrategy: customStrategy, // Custom data loading getContext: createContext, // Custom context patchRoutesOnNavigation: patchFn, // Dynamic routes unstable_instrumentations: [logger] // Instrumentation }); ``` ## Conclusion React Router v7 provides a mature, type-safe routing solution with automatic TypeScript support. Its familiar API for v6 users, combined with modern features like middleware, server-side rendering support, and comprehensive type generation, makes it a strong choice for building scalable React applications. The key advantage over alternatives is the seamless integration with existing React patterns (hooks, components) and the framework's approach to type safety through automatic code generation rather than manual annotations.