Welcome, {user.name}
-
{items.map((item) => (
- {item.title} ))}
Post {postId} by User {userId}
; } ``` All parameter values are strings. Parse numbers or other types explicitly: ```tsx const { id } = useParams(); const numericId = Number(id); // Convert when needed ``` #### useSearchParams Read and update query string parameters without a full navigation: ```tsx 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 (Products{category ? `: ${category}` : ""} (Page {page})
{navigation.state === "loading" &&
);
}
```
| Property | Type | Description |
|---|---|---|
| `state` | `"idle" \| "loading" \| "submitting"` | Current navigation state |
| `location` | `Location \| undefined` | Target location (when loading) |
| `formData` | `FormData \| undefined` | Submitted form data (when submitting) |
| `formAction` | `string \| undefined` | Action URL being submitted to |
| `formMethod` | `string \| undefined` | HTTP method of the submission |
| `formEncType` | `string \| undefined` | Encoding type of the submission |
#### useBlocker
Block navigation when the user has unsaved changes:
```tsx
import { useBlocker } from "react-router";
function EditForm() {
const [isDirty, setIsDirty] = useState(false);
const blocker = useBlocker(isDirty);
return (
Saving...
}
{blocker.state === "blocked" && (
)}
);
}
```
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:
```tsx
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 ;
}
```
> [!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:
```tsx
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 (
You have unsaved changes. Leave anyway?
-
{users.map((user) => (
- {user.name} ))}
setQuery(e.target.value)}
placeholder="Search users..."
/>
{fetcher.state === "loading" &&
);
}
```
| Fetcher property | Description |
|---|---|
| `fetcher.state` | `"idle"`, `"loading"`, or `"submitting"` |
| `fetcher.data` | The data returned by the loader or action |
| `fetcher.formData` | The FormData being submitted |
| `fetcher.formAction` | The action URL |
| `fetcher.formMethod` | The HTTP method |
| `fetcher.Form` | A `
);
}
// 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 ;
}
// 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 ;
}
```
### 4.8 URL and Path Utilities
#### useHref
Resolve a `to` value into a full href string:
```tsx
import { useHref } from "react-router";
function ExternalForm() {
// Resolves against the current basename
const href = useHref("/submit");
return ;
}
```
#### useResolvedPath
Resolve a relative path against the current location:
```tsx
import { useResolvedPath } from "react-router";
function Breadcrumb() {
const resolved = useResolvedPath("..");
// resolved.pathname — parent route's path
return Back;
}
```
#### useMatch
Check if the current URL matches a specific pattern:
```tsx
import { useMatch } from "react-router";
function AdminBadge() {
const match = useMatch("/admin/*");
if (!match) return null;
return Admin Area;
}
// Access captured params
function UserBanner() {
const match = useMatch("/users/:id");
if (!match) return null;
return -
{fetcher.data.users.map((u) => (
- {u.name} ))}
Viewing user {match.params.id}
; } ``` #### useMatches Get all matched routes in the current hierarchy. Each match includes the route's `id`, `pathname`, `params`, `data` (loader data), and `handle`: ```tsx import { useMatches } from "react-router"; function Breadcrumbs() { const matches = useMatches(); return ( ); } ``` #### useFormAction Resolve the action URL for the current route: ```tsx 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 ; } ``` #### useLinkClickHandler Build custom navigation components with full control over click handling: ```tsx import { useLinkClickHandler } from "react-router"; function TrackedLink({ to, children, ...props }) { const handleClick = useLinkClickHandler(to); return ( { analytics.track("link_click", { to }); handleClick(event); }} {...props} > {children} ); } ``` ### 4.9 View Transitions React Router integrates with the browser's View Transitions API for animated page transitions: ```tsx import { Link, NavLink, useNavigate, useViewTransitionState } from "react-router"; // Enable via Link View Photo // Enable via NavLink{loaderData.product.name}
; } ``` The `href()` utility provides type-safe path construction: ```tsx import { href } from "react-router"; // TypeScript errors if the route pattern or params are wrong Product 42 // No params needed for static routes About // Optional params Blog Post Blog Index ``` ### 4.11 Standalone Utility Functions These functions work outside of React components — in loaders, actions, tests, or plain JavaScript. #### Path Matching and Generation ```tsx import { matchPath, matchRoutes, generatePath } from "react-router"; // Match a single path pattern against a URL const match = matchPath("/users/:id", "/users/42"); if (match) { console.log(match.params.id); // "42" console.log(match.pathname); // "/users/42" console.log(match.pattern); // { path: "/users/:id" } } // Match with options matchPath({ path: "/users/:id", end: false }, "/users/42/posts"); // Matches (end: false allows trailing segments) // Match against a route tree const routes = [ { path: "/", children: [ { path: "users/:id" }, { path: "posts/:postId" }, ], }, ]; const matches = matchRoutes(routes, "/users/42"); // Returns array of matched route objects with params // Generate a path from a pattern + params const path = generatePath("/users/:id/posts/:postId", { id: "42", postId: "7", }); // Returns "/users/42/posts/7" // Splat params generatePath("/files/*", { "*": "docs/readme.md" }); // Returns "/files/docs/readme.md" ``` #### Path Manipulation ```tsx import { createPath, parsePath, resolvePath } from "react-router"; // Create a path string from parts createPath({ pathname: "/users", search: "?page=2", hash: "#top", }); // Returns "/users?page=2#top" // Parse a path string into parts parsePath("/users?page=2#top"); // Returns { pathname: "/users", search: "?page=2", hash: "#top" } // Resolve a relative path against a base resolvePath("settings", "/dashboard"); // Returns { pathname: "/dashboard/settings", search: "", hash: "" } resolvePath("..", "/dashboard/settings"); // Returns { pathname: "/dashboard", search: "", hash: "" } ``` #### Response Helpers Use these in loaders and actions to create standardized responses: ```tsx import { redirect, redirectDocument, replace, data } from "react-router"; // Client-side redirect (SPA navigation) export async function action() { await saveData(); return redirect("/success"); } // Redirect with status code return redirect("/login", 302); // Redirect with headers return redirect("/dashboard", { headers: { "Set-Cookie": await commitSession(session) }, }); // Full document redirect (bypasses client-side routing, full page reload) export async function action() { return redirectDocument("/external-page"); } // Replace current history entry (navigates but no new history entry) export async function action() { return replace("/dashboard"); } // Typed response with custom status and headers export async function loader() { return data( { items: await getItems() }, { status: 200, headers: { "Cache-Control": "public, max-age=3600", "X-Custom-Header": "value", }, } ); } // Error responses (caught by error boundaries) export async function loader({ params }) { const item = await getItem(params.id); if (!item) { throw data( { message: "Item not found" }, { status: 404 } ); } return { item }; } ``` #### Route Conversion Utilities ```tsx import { createRoutesFromElements } from "react-router"; // Convert JSX route elements to route objects // Useful if you have JSX routes but need to pass them to createBrowserRouter const routes = createRoutesFromElements(
{/* GET form — submits to the current URL with query params */}
);
}
```
### 5.4 Optimistic UI
Update the UI immediately before the server responds, then reconcile when the response arrives:
```tsx
function FavoriteButton({ item }) {
const fetcher = useFetcher();
// Use the optimistic value while the request is in flight
const isFavorite = fetcher.formData
? fetcher.formData.get("favorite") === "true"
: item.isFavorite;
return (
{total} results
{products.map((product) => (-
{optimisticTodos.map((todo) => (
{navigation.state !== "idle" && (
)}
);
}
```
#### Busy Submit Button
```tsx
function SubmitButton({ label = "Save" }) {
const navigation = useNavigation();
const isSubmitting = navigation.state === "submitting";
return (
);
}
```
#### Skeleton UI While Loading a Specific Route
```tsx
function DashboardLink() {
const navigation = useNavigation();
const isLoadingDashboard =
navigation.state === "loading" &&
navigation.location?.pathname === "/dashboard";
return (
Dashboard
{isLoadingDashboard &&
);
}
```
### 5.6 Error Handling Patterns
#### Granular Error Boundaries
Place error boundaries at different levels for targeted error recovery:
```tsx
const router = createBrowserRouter([
{
path: "/",
element: Not Found
The resource you requested does not exist.
Go HomeAccess Denied
You do not have permission to view this page.
Error {error.status}
{error.statusText}
Something went wrong
{error instanceof Error ? error.message : "Unknown error"}
Failed to load data
{error instanceof Error ? error.message : "Unknown error"}
{photos.map((photo) => (
))}
);
}
// Modal component
function PhotoModal() {
const { id } = useParams();
const navigate = useNavigate();
return (
navigate(-1)}>
);
}
```
When the user navigates directly to `/photos/42` (e.g., from a bookmark), there is no `backgroundLocation` in state, so `PhotoPage` renders as a full page instead of a modal.
### 5.8 Breadcrumbs
Build breadcrumbs using the `handle` property and `useMatches`:
```tsx
// Define breadcrumbs in route configuration
const router = createBrowserRouter([
{
id: "root",
path: "/",
element: e.stopPropagation()}>
User {userId}
; } ``` #### Optional Parameters (Framework Mode FS Routing) ```tsx // File: routes/blog.($slug).tsx // Matches: /blog (no slug) AND /blog/my-post (with slug) export default function Blog() { const { slug } = useParams(); if (!slug) { returnOrg {orgId}, Team {teamId}, Member {memberId}
); } ``` ### 5.10 Meta and Links (Framework Mode) #### Setting Page Metadata ```tsx import type { Route } from "./+types/my-route"; export const meta: Route.MetaFunction = ({ data, params, location }) => { return [ { title: `${data.product.name} | My Store` }, { name: "description", content: data.product.description }, { property: "og:title", content: data.product.name }, { property: "og:image", content: data.product.image }, { property: "og:url", content: `https://mystore.com${location.pathname}` }, { "script:ld+json": { "@context": "https://schema.org", "@type": "Product", name: data.product.name, description: data.product.description, }, }, ]; }; ``` Meta from child routes replaces parent route meta by default. To merge parent meta: ```tsx export const meta: Route.MetaFunction = ({ data, matches }) => { // Get parent meta const parentMeta = matches.flatMap((match) => match.meta ?? []); return [ ...parentMeta, { title: `${data.title} | My App` }, ]; }; ``` #### Adding Link Tags ```tsx export const links: Route.LinksFunction = () => { return [ { rel: "stylesheet", href: "/styles/product.css" }, { rel: "preload", href: "/fonts/Inter.woff2", as: "font", type: "font/woff2", crossOrigin: "anonymous", }, { rel: "canonical", href: "https://mystore.com/products/42" }, { rel: "icon", href: "/favicon.svg", type: "image/svg+xml" }, ]; }; ``` #### Custom HTTP Headers ```tsx export const headers: Route.HeadersFunction = ({ loaderHeaders, parentHeaders, actionHeaders, errorHeaders, }) => { return { "Cache-Control": loaderHeaders.get("Cache-Control") || "public, max-age=300", "X-Custom-Header": "value", }; }; ``` ### 5.11 Revalidation Control Fine-tune when loaders re-run after navigations and actions: ```tsx export function shouldRevalidate({ currentUrl, currentParams, nextUrl, nextParams, formAction, formMethod, defaultShouldRevalidate, actionResult, }) { // Skip revalidation if only the hash changed if (currentUrl.pathname === nextUrl.pathname && currentUrl.search === nextUrl.search) { return false; } // Always revalidate after non-GET submissions if (formMethod && formMethod !== "GET") { return true; } // Only revalidate if specific params changed if (currentParams.category !== nextParams.category) { return true; } // Fall back to React Router's default behavior return defaultShouldRevalidate; } ``` ### 5.12 Polling and Real-Time Updates #### Polling with useRevalidator ```tsx function LiveDashboard() { const { data } = useLoaderData(); const revalidator = useRevalidator(); useEffect(() => { const interval = setInterval(() => { if (revalidator.state === "idle") { revalidator.revalidate(); } }, 30_000); // Poll every 30 seconds return () => clearInterval(interval); }, [revalidator]); return
= 1 ? "active" : ""}>1. Info
= 2 ? "active" : ""}>2. Address
= 3 ? "active" : ""}>3. Review