| 1 | ---
|
| 2 | title: Picking a Mode
|
| 3 | order: 1
|
| 4 | ---
|
| 5 |
|
| 6 | # Picking a Mode
|
| 7 |
|
| 8 | React Router is a multi-strategy router for React. There are three primary ways, or "modes", to use it in your app. Across the docs you'll see these icons indicating which mode the content is relevant to:
|
| 9 |
|
| 10 | [MODES: framework, data, declarative]
|
| 11 |
|
| 12 | <p></p>
|
| 13 |
|
| 14 | The features available in each mode are additive, so moving from Declarative to Data to Framework simply adds more features at the cost of architectural control. So pick your mode based on how much control or how much help you want from React Router.
|
| 15 |
|
| 16 | The mode depends on which "top level" router API you're using:
|
| 17 |
|
| 18 | ## Declarative
|
| 19 |
|
| 20 | Declarative mode enables basic routing features like matching URLs to components, navigating around the app, and providing active states with APIs like `<Link>`, `useNavigate`, and `useLocation`.
|
| 21 |
|
| 22 | ```tsx
|
| 23 | import { BrowserRouter } from "react-router";
|
| 24 |
|
| 25 | ReactDOM.createRoot(root).render(
|
| 26 | <BrowserRouter>
|
| 27 | <App />
|
| 28 | </BrowserRouter>,
|
| 29 | );
|
| 30 | ```
|
| 31 |
|
| 32 | ## Data
|
| 33 |
|
| 34 | By moving route configuration outside of React rendering, Data Mode adds data loading, actions, pending states and more with APIs like `loader`, `action`, and `useFetcher`.
|
| 35 |
|
| 36 | ```tsx
|
| 37 | import {
|
| 38 | createBrowserRouter,
|
| 39 | RouterProvider,
|
| 40 | } from "react-router";
|
| 41 |
|
| 42 | let router = createBrowserRouter([
|
| 43 | {
|
| 44 | path: "/",
|
| 45 | Component: Root,
|
| 46 | loader: loadRootData,
|
| 47 | },
|
| 48 | ]);
|
| 49 |
|
| 50 | ReactDOM.createRoot(root).render(
|
| 51 | <RouterProvider router={router} />,
|
| 52 | );
|
| 53 | ```
|
| 54 |
|
| 55 | ## Framework
|
| 56 |
|
| 57 | Framework Mode wraps Data Mode with a Vite plugin to add the full React Router experience with:
|
| 58 |
|
| 59 | - type-safe `href`
|
| 60 | - type-safe Route Module API
|
| 61 | - intelligent code splitting
|
| 62 | - SPA, SSR, and static rendering strategies
|
| 63 | - and more
|
| 64 |
|
| 65 | ```ts filename=routes.ts
|
| 66 | import { index, route } from "@react-router/dev/routes";
|
| 67 |
|
| 68 | export default [
|
| 69 | index("./home.tsx"),
|
| 70 | route("products/:pid", "./product.tsx"),
|
| 71 | ];
|
| 72 | ```
|
| 73 |
|
| 74 | You'll then have access to the Route Module API with type-safe params, loaderData, code splitting, SPA/SSR/SSG strategies, and more.
|
| 75 |
|
| 76 | ```ts filename=product.tsx
|
| 77 | import { Route } from "./+types/product.tsx";
|
| 78 |
|
| 79 | export async function loader({ params }: Route.LoaderArgs) {
|
| 80 | let product = await getProduct(params.pid);
|
| 81 | return { product };
|
| 82 | }
|
| 83 |
|
| 84 | export default function Product({
|
| 85 | loaderData,
|
| 86 | }: Route.ComponentProps) {
|
| 87 | return <div>{loaderData.product.name}</div>;
|
| 88 | }
|
| 89 | ```
|
| 90 |
|
| 91 | ## Decision Advice
|
| 92 |
|
| 93 | Every mode supports any architecture and deployment target, so the question isn't really about if you want SSR, SPA, etc. It's about how much you want to do yourself.
|
| 94 |
|
| 95 | **Use Framework Mode if you:**
|
| 96 |
|
| 97 | - are too new to have an opinion
|
| 98 | - are considering Next.js, Solid Start, SvelteKit, Astro, TanStack Start, etc. and want to compare
|
| 99 | - just want to build something with React
|
| 100 | - might want to server render, might not
|
| 101 | - are migrating from Next.js
|
| 102 |
|
| 103 | [→ Get Started with Framework Mode](./framework/installation).
|
| 104 |
|
| 105 | **Use Data Mode if you:**
|
| 106 |
|
| 107 | - want data features but also want to have control over bundling, data, and server abstractions
|
| 108 | - started a data router in v6.4 and are happy with it
|
| 109 |
|
| 110 | [→ Get Started with Data Mode](./data/custom).
|
| 111 |
|
| 112 | **Use Declarative Mode if you:**
|
| 113 |
|
| 114 | - want to use React Router as simply as possible
|
| 115 | - are coming from earlier React Router versions and are happy with the `<BrowserRouter>`
|
| 116 | - have a data layer that either skips pending states (like local first, background data replication/sync) or has its own abstractions for them
|
| 117 | - are coming from Create React App (you may want to consider framework mode though)
|
| 118 |
|
| 119 | [→ Get Started with Declarative Mode](./declarative/installation).
|
| 120 |
|
| 121 | ## API + Mode Availability Table
|
| 122 |
|
| 123 | This is mostly for the LLMs, but knock yourself out:
|
| 124 |
|
| 125 | | API | Framework | Data | Declarative |
|
| 126 | | ------------------------------ | --------- | ---- | ----------- |
|
| 127 | | Await | ✅ | ✅ | |
|
| 128 | | Form | ✅ | ✅ |
|
| 129 | | Link | ✅ | ✅ | ✅ |
|
| 130 | | `<Link discover>` | ✅ | | |
|
| 131 | | `<Link prefetch>` | ✅ | | |
|
| 132 | | `<Link preventScrollReset>` | ✅ | ✅ | |
|
| 133 | | Links | ✅ | | |
|
| 134 | | Meta | ✅ | | |
|
| 135 | | NavLink | ✅ | ✅ | ✅ |
|
| 136 | | `<NavLink discover>` | ✅ | | |
|
| 137 | | `<NavLink prefetch>` | ✅ | | |
|
| 138 | | `<NavLink preventScrollReset>` | ✅ | ✅ | |
|
| 139 | | NavLink `isPending` | ✅ | ✅ | |
|
| 140 | | Navigate | ✅ | ✅ | ✅ |
|
| 141 | | Outlet | ✅ | ✅ | ✅ |
|
| 142 | | PrefetchPageLinks | ✅ | | |
|
| 143 | | Route | ✅ | ✅ | ✅ |
|
| 144 | | Routes | ✅ | ✅ | ✅ |
|
| 145 | | Scripts | ✅ | | |
|
| 146 | | ScrollRestoration | ✅ | ✅ | |
|
| 147 | | ServerRouter | ✅ | | |
|
| 148 | | usePrompt | ✅ | ✅ | |
|
| 149 | | useActionData | ✅ | ✅ | |
|
| 150 | | useAsyncError | ✅ | ✅ | |
|
| 151 | | useAsyncValue | ✅ | ✅ | |
|
| 152 | | useBeforeUnload | ✅ | ✅ | ✅ |
|
| 153 | | useBlocker | ✅ | ✅ | |
|
| 154 | | useFetcher | ✅ | ✅ | |
|
| 155 | | useFetchers | ✅ | ✅ | |
|
| 156 | | useFormAction | ✅ | ✅ | |
|
| 157 | | useHref | ✅ | ✅ | ✅ |
|
| 158 | | useInRouterContext | ✅ | ✅ | ✅ |
|
| 159 | | useLinkClickHandler | ✅ | ✅ | ✅ |
|
| 160 | | useLoaderData | ✅ | ✅ | |
|
| 161 | | useLocation | ✅ | ✅ | ✅ |
|
| 162 | | useMatch | ✅ | ✅ | ✅ |
|
| 163 | | useMatches | ✅ | ✅ | |
|
| 164 | | useNavigate | ✅ | ✅ | ✅ |
|
| 165 | | useNavigation | ✅ | ✅ | |
|
| 166 | | useNavigationType | ✅ | ✅ | ✅ |
|
| 167 | | useOutlet | ✅ | ✅ | ✅ |
|
| 168 | | useOutletContext | ✅ | ✅ | ✅ |
|
| 169 | | useParams | ✅ | ✅ | ✅ |
|
| 170 | | useResolvedPath | ✅ | ✅ | ✅ |
|
| 171 | | useRevalidator | ✅ | ✅ | |
|
| 172 | | useRouteError | ✅ | ✅ | |
|
| 173 | | useRouteLoaderData | ✅ | ✅ | |
|
| 174 | | useRoutes | ✅ | ✅ | ✅ |
|
| 175 | | useSearchParams | ✅ | ✅ | ✅ |
|
| 176 | | useSubmit | ✅ | ✅ | |
|
| 177 | | useViewTransitionState | ✅ | ✅ | |
|
| 178 | | isCookieFunction | ✅ | ✅ | |
|
| 179 | | isSessionFunction | ✅ | ✅ | |
|
| 180 | | createCookie | ✅ | ✅ | |
|
| 181 | | createCookieSessionStorage | ✅ | ✅ | |
|
| 182 | | createMemorySessionStorage | ✅ | ✅ | |
|
| 183 | | createPath | ✅ | ✅ | ✅ |
|
| 184 | | createRoutesFromElements | | ✅ | |
|
| 185 | | createRoutesStub | ✅ | ✅ | |
|
| 186 | | createSearchParams | ✅ | ✅ | ✅ |
|
| 187 | | data | ✅ | ✅ | |
|
| 188 | | generatePath | ✅ | ✅ | ✅ |
|
| 189 | | href | ✅ | | |
|
| 190 | | isCookie | ✅ | ✅ | |
|
| 191 | | isRouteErrorResponse | ✅ | ✅ | |
|
| 192 | | isSession | ✅ | ✅ | |
|
| 193 | | matchPath | ✅ | ✅ | ✅ |
|
| 194 | | matchRoutes | ✅ | ✅ | ✅ |
|
| 195 | | parsePath | ✅ | ✅ | ✅ |
|
| 196 | | redirect | ✅ | ✅ | |
|
| 197 | | redirectDocument | ✅ | ✅ | |
|
| 198 | | renderMatches | ✅ | ✅ | ✅ |
|
| 199 | | replace | ✅ | ✅ | |
|
| 200 | | resolvePath | ✅ | ✅ | ✅ |
|