version: "1.0.0" name: react-router-framework-mode description: Build full-stack React applications using React Router's framework mode. Use when configuring routes, working with loaders and actions, handling forms, handling navigation, pending/optimistic UI, error boundaries, or working with react-router.config.ts or other react router conventions. license: MIT

React Router Framework Mode

Framework mode is React Router's full-stack development experience with file-based routing, server-side, client-side, and static rendering strategies, data loading and mutations, and type-safe route module API.

When to Apply

• Configuring new routes (app/routes.ts)
• Loading data with loader or clientLoader
• Handling mutations with action or clientAction
• Navigating with <Link>, <NavLink>, <Form>, redirect, and useNavigate
• Implementing pending/loading UI states
• Configuring SSR, SPA mode, or pre-rendering (react-router.config.ts)
• Implementing authentication

References

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

Version Compatibility

Some features require specific React Router versions. Always verify before implementing:

npm list react-router

Critical Patterns

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

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?.get("favorite") === "true" ?? isFavorite;
<fetcher.Form method="post" action={`/favorites/${id}`}>
  <button>{optimistic ? "★" : "☆"}</button>
</fetcher.Form>;

See references/actions.md for complete patterns.

Layouts

Global UI belongs in `root.tsx` - don't create separate layout files for nav/footer:

// app/root.tsx - add navigation, footer, providers here
export default function App() {
  return (
    <div>
      <nav>...</nav>
      <Outlet />
      <footer>...</footer>
    </div>
  );
}

Use nested routes for section-specific layouts. See references/routing.md.

Route Module Exports

`meta` uses `loaderData`, not deprecated data:

// ✅ Correct
export function meta({ loaderData }: Route.MetaArgs) { ... }
// ❌ Wrong - `data` is deprecated
export function meta({ data }: Route.MetaArgs) { ... }

See references/route-modules.md for all exports.

Further Documentation

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

https://reactrouter.com/docs