Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 50 ยท Getting Started

Choosing Between Declarative, Data and Framework Mode

Compare React Router 7's declarative, data and framework modes, learn which imports each uses, how to upgrade between them and how to pick the right one.

React Router 7 gives you three ways to use the same library, and picking one is the first real decision of a project. The wrong choice is rarely a disaster, because the modes are layers and you can move up, but it helps to know what you are choosing. A small marketing site does not need a server rendering framework, and an app full of forms and tables is a poor fit for pages that fetch data inside effects.

This lesson compares the three modes feature by feature, shows which imports belong to which, walks through the upgrade path with read-only code, and ends with a decision guide you can run. Everything here applies to the rest of the course: lessons in the "Declarative Routing Basics" chapter work in all three modes, lessons in "Data Mode" work in data and framework mode, and the last chapters cover framework mode.

The three modes in one picture

flowchart TD
  F["Framework mode<br/>Vite plugin, routes.ts, SSR,<br/>route modules, typegen"] --> D["Data mode<br/>createBrowserRouter, RouterProvider,<br/>loaders, actions, Form"]
  D --> C["Declarative mode<br/>BrowserRouter, Routes, Route,<br/>Link, navigation hooks"]

Each mode contains the one below it: framework mode is data mode plus a build tool and a server.

Declarative mode is the classic style. You render <BrowserRouter>, describe routes with JSX and your components fetch their own data. The router knows about the URL and nothing else.

Data mode keeps your app a client-side single-page app, but the route objects you pass to createBrowserRouter can carry more than a path and a component: a loader that fetches data before rendering, an action that handles form submissions, an errorElement for failures, and a lazy function for code splitting. The router coordinates all of that, including pending states and automatic data refresh after a mutation.

Framework mode adds a build plugin (for Vite), a routes file, and a server. You write route modules, files that export a component plus loader, action, meta and so on, and the framework generates the router, splits the code for each route, renders pages on the server (optionally), pre-renders static pages and generates TypeScript types for each route's params and data. If you remember Remix, this is Remix's job, now inside React Router.

What each mode includes

This table lists the features you will meet in this course and whether the mode provides them out of the box. "Built-in" for server rendering means the framework wires it up for you: with a data router you can also render on a server by hand, but you assemble it yourself.

Compare the modes feature by feature

Switch between the modes and watch the "No" entries shrink. Two details that surprise people: hooks such as useNavigation and components such as ScrollRestoration are not available in declarative mode, because they depend on the data router that createBrowserRouter creates. If you call them under <BrowserRouter> they throw an error.

Imports: react-router, react-router-dom and friends

In version 7 almost everything comes from one package:

JSX
// Real React Router 7 imports (read-only)

// All modes: components and hooks
import { Link, NavLink, Outlet, useParams, useNavigate } from 'react-router';

// Declarative mode
import { BrowserRouter, Routes, Route } from 'react-router';

// Data mode: the router is created in 'react-router', the DOM provider is in a subpath
import { createBrowserRouter } from 'react-router';
import { RouterProvider } from 'react-router/dom';

// Framework mode: config helpers for routes.ts and the dev plugin
import { route, index, layout } from '@react-router/dev/routes';
import { reactRouter } from '@react-router/dev/vite';

react-router-dom was the browser package in versions 5 and 6, and version 6 tutorials import everything from it. In version 7 it is only a re-export of react-router, kept so existing code does not break. New code should import from react-router, and existing projects can switch with a find-and-replace. The packages for framework mode are @react-router/dev (build tooling), @react-router/node and @react-router/serve (a Node server and a ready-made runner), and others for Cloudflare and similar hosts. The migration guide lists the exact steps.

The separate RouterProvider import from react-router/dom is a version 7 detail that confuses many people. The reason is that the DOM-specific bits (such as the batched React updates) live in the dom subpath, and the main entry stays environment neutral. If an example does not compile, check this import first.

Upgrading from one mode to the next

Because the modes are layers, upgrading is mostly moving code, not rewriting it. Your components, Links, useParams calls and layouts keep working.

Declarative to data. Replace <BrowserRouter> and <Routes> with a router object. You can even keep your JSX routes by converting them:

JSX
// Declarative (before, read-only)
<BrowserRouter>
  <Routes>
    <Route path="/" element={<Layout />}>
      <Route index element={<Home />} />
      <Route path="products/:id" element={<Product />} />
    </Route>
  </Routes>
</BrowserRouter>

// Data mode (after, read-only): same routes, written as objects
const router = createBrowserRouter([
  {
    path: '/',
    Component: Layout,
    children: [
      { index: true, Component: Home },
      { path: 'products/:id', Component: Product },
    ],
  },
]);

<RouterProvider router={router} />

Now each route may gain a loader, an action and an errorElement one at a time. Routes as Objects: useRoutes and Route Configs and createBrowserRouter and RouterProvider cover this step.

Data to framework. The route objects turn into a routes.ts file, and each component moves into its own route module:

TypeScript
// app/routes.ts (read-only)
import { type RouteConfig, route, index, layout } from '@react-router/dev/routes';

export default [
  layout('./layout.tsx', [
    index('./home.tsx'),
    route('products/:id', './product.tsx'),
  ]),
] satisfies RouteConfig;
TSX
// app/product.tsx: a route module (read-only)
import type { Route } from './+types/product';

export async function loader({ params }: Route.LoaderArgs) {
  return { product: await getProduct(params.id) };
}

export default function Product({ loaderData }: Route.ComponentProps) {
  return <h1>{loaderData.product.name}</h1>;
}

The loader function is the same idea as in data mode. What changes is the packaging: the file name replaces the route object, and types and server rendering come with the framework. Framework Mode Overview takes it from here.

A decision guide

There is no wrong answer, only trade-offs. Walk through these questions in order.

flowchart TD
  Q1{"Need server rendering,<br/>pre-rendering or generated types?"}
  Q1 -->|"yes"| FW["Framework mode"]
  Q1 -->|"no"| Q2{"Do screens load data or<br/>submit forms through routes?"}
  Q2 -->|"yes"| DM["Data mode"]
  Q2 -->|"no"| DC["Declarative mode"]

Start from the top; stop at the first question you answer yes to.

The runnable guide below turns the same questions into checkboxes. It is a teaching aid, not a rule: the answer shows the lowest mode that covers what you ticked.

Which mode do I need?

Tick "Forms should submit through the router and refresh data" and the answer jumps to data mode; tick "Search engines must see rendered HTML" and it jumps to framework mode. Some rules of thumb behind the guide:

  • Dashboards, internal tools and apps behind a login rarely need server rendering. Data mode is usually the sweet spot.
  • Public content that must rank in search engines (blogs, shops, documentation) benefits from framework mode, because the HTML arrives already rendered. Client-side apps can still rank, but crawlers and slow phones have more work to do.
  • Existing projects can stay in declarative mode forever. Moving up is optional.
  • Learning: this course teaches declarative routing first because it carries over to every mode, then data mode, then framework mode.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which statement about the three modes is true?

    The modes are layers of the same library: framework mode adds a build tool and a server to data mode, which adds loaders and actions to declarative routing.
  2. 2. Which of these needs a data router (createBrowserRouter) and therefore does not work under BrowserRouter?

    useNavigation reports the state of router-managed navigations and submissions, which only exists when a data router is running. Link, useParams and Outlet work in every mode.
  3. 3. In React Router 7, where should you import BrowserRouter and Link from in new code?

    Version 7 puts everything in react-router. The package react-router-dom still exists as a re-export for existing code.
  4. 4. You are building a public blog that must be indexed with fully rendered HTML. Which mode fits best?

    Framework mode renders pages on the server or at build time, so crawlers and browsers receive finished HTML. Declarative and data mode render in the browser.

Summary

  • The three modes are layers: declarative (matching and links), data (adds loaders, actions, pending and error handling) and framework (adds a build plugin, route modules, server rendering and generated types).
  • Some features, such as useNavigation, useBlocker and ScrollRestoration, need a data router and are unavailable under BrowserRouter.
  • In version 7 import from react-router; RouterProvider comes from react-router/dom, and react-router-dom is only a re-export.
  • Upgrading means moving code: JSX routes become route objects, and route objects become a routes.ts file plus route modules.
  • Pick the lowest mode that covers your needs: server rendering or generated types point to framework mode, router-owned data and forms point to data mode, everything else to declarative mode.

Next: Routes and Matching