State Management

React Router fundamentally changes how you think about client-side state. Its loader/action pattern handles the most common use case for global state management libraries, such as Redux, React Query, or Zustand: fetching server data and keeping it synchronized after mutations. Since React Router manages this natively, you typically don’t need a separate library for such remote state.

What this means in practice: A server-centric model replaces the classic client-side fetch-on-mount, store-in-state, manually-invalidate cycle:

1. Route enters, loader() runs, and then data flows into the component. For example, data flows via the useLoaderData() hook.
2. User submits form, action() runs, and then React Router revalidates all loaders automatically.

This is the central state management pattern in React Router. It replaces client-side data fetching patterns, such as fetch-on-mount and manual cache invalidation, with a declarative, server-centric model.

• A loader runs on the server before the route renders. Its return value becomes the component’s data via useLoaderData().
• An action handles mutations. After it completes, React Router automatically revalidates all active loaders. React Router manages the data lifecycle entirely.

For loader, data classification (critical vs. non-critical), streaming patterns, action processing, and resource routes, see Data Fetching.

The <Form> component serializes form state into FormData and submits it to the route’s action. After the action completes, React Router revalidates all active loaders automatically. This is the primary mutation pattern when the operation should trigger a navigation or a full-page state update.

For action arguments, validation patterns, and examples, see Data Fetching.

useFetcher triggers loaders and actions without causing navigation. It gives each component its own mutation lifecycle, making it suitable for inline edits, autosave, toggling, and any mutation that shouldn’t change the URL.

From a state management perspective, each fetcher exposes its own lifecycle. fetcher.state exposes the mutation lifecycle while fetcher.data holds the action’s return value. This enables per-component feedback (for example, inline validation errors) without global state.

For fetcher usage patterns and resource routes, see Data Fetching. For visual feedback patterns based on fetcher.state, see Loading States.

useRouteLoaderData accesses the loader data of any currently active route by its route ID. This avoids prop-drilling when a child route needs data that a parent or sibling route already loaded.

A common use case is accessing root-level data, such as session, locale, or site configuration, from deeply nested routes without passing it through every intermediate layout. The route ID passed to useRouteLoaderData must match the route’s id as defined in the route configuration. The hook returns undefined if the target route isn’t currently active.

1// routes/root.tsx
2export async function loader() {
3  const user = await getUser();
4  const locale = await getLocale();
5  return { user, locale };
6}
7
8// routes/products/product-detail.tsx
9import { useRouteLoaderData } from "react-router";
10
11export default function ProductDetail() {
12  const rootData = useRouteLoaderData < typeof rootLoader > "root";
13  return <p>Welcome, {rootData?.user?.name}</p>;
14}

Middleware context is React Router’s mechanism for request-scoped dependency injection. Middlewares run in a pipeline before loaders and actions, populating a typed context object with data that all downstream loaders and actions can access. This eliminates the need for loaders to independently resolve cross-cutting concerns such as sessions, app configuration, or API clients.

For middleware definition, pipeline ordering, and writing middleware functions, see Data Fetching.

useNavigation exposes the global navigation state, useful for pending UI during route transitions.

1import { useNavigation } from "react-router";
2
3function GlobalSpinner() {
4  const navigation = useNavigation();
5  if (navigation.state === "idle") {
6    return null;
7  }
8  return <Spinner />;
9}

navigation.formData is available during form submissions, enabling optimistic UI based on the submitted values before the server responds. For loading state patterns in detail, see Loading States.

The URL is a state container. Search parameters, path parameters, and the location object are reactive state sources that survive page refreshes, are shareable via links, and integrate with the browser’s history stack.

useSearchParams reads and writes URL query parameters. It replaces useState for state that should be reflected in the URL, such as filters, pagination, sort order, or modal visibility.

When to use useSearchParams over useState: If the state should survive a page refresh, be shareable via URL, or be accessible to loaders (via request.url), it belongs in search params.

1import { useSearchParams } from "react-router";
2
3function ProductFilters() {
4  const [searchParams, setSearchParams] = useSearchParams();
5  const category = searchParams.get("category") ?? "all";
6
7  return (
8    <select value={category} onChange={(e) => setSearchParams({ category: e.target.value })}>
9      <option value="all">All</option>
10      <option value="shoes">Shoes</option>
11      <option value="bags">Bags</option>
12    </select>
13  );
14}

useParams returns the dynamic path parameters for the current route. It’s read-only and reactive, the component re-renders when the route changes.

1import { useParams } from "react-router";
2
3function ProductDetail() {
4  const { productId } = useParams();
5  // productId is derived from the URL, e.g., /products/:productId
6}

Sometimes, state must survive page refreshes and revisits without belonging to the URL. Examples include user preferences (theme, locale, dismissed banners), shopping cart identifiers, and authentication tokens. Cookies and server sessions are React Router’s native mechanism for this kind of persistent state.

Unlike useState (transient) or useSearchParams (URL-visible), cookies travel with every HTTP request and are available in loaders and actions on the server. This behavior makes cookies a single source of truth that requires no client-side synchronization, avoids localStorage SSR issues, and works even before scripts load.

React Router provides createCookie for simple key-value cookies and createCookieSessionStorage for structured, typed session data. Both integrate directly with the loader/action lifecycle: cookies are read via request.headers.get('Cookie') and written via Set-Cookie response headers.

For details on cookies and sessions APIs, see Data Fetching.

Optimistic UI updates the interface immediately, before the server confirms the mutation, and rolls back if the operation fails. React Router and React offer complementary approaches, each suited to a different kind of state.

useFetcher exposes the submitted formData while an action is in flight. This enables optimistic reads directly from the pending submission without additional state management. This pattern requires no extra hooks and works with any version of React. It’s the idiomatic React Router approach for simple optimistic updates derived from the submitted form values.

1const fetcher = useFetcher();
2
3const isComplete = fetcher.formData ? fetcher.formData.get("complete") === "true" : item.complete;
4
5return (
6  <fetcher.Form method="post" action="/api/toggle">
7    <input type="hidden" name="complete" value={String(!item.complete)} />
8    <button type="submit">{isComplete ? "✓ Complete" : "Mark complete"}</button>
9  </fetcher.Form>
10);

When state is serialized into URL search parameters and updates trigger a navigate() call, useNavigation() provides a navigation-aware optimistic path. While a navigation is pending, navigation.location holds the target Location object. Reading the intended query parameters from that target reflects the user’s action immediately, without any local state to manage.

1import { useNavigation } from "react-router";
2
3function Filters({ items }) {
4  const navigation = useNavigation();
5
6  // While a navigation is pending, read from the target URL.
7  // Once it settles, fall back to the server-provided props.
8  const effectiveItems = navigation.location
9    ? new URLSearchParams(navigation.location.search).getAll("item")
10    : items;
11
12  return (
13    <ul>
14      {effectiveItems.map((item) => (
15        <li key={item}>{item}</li>
16      ))}
17    </ul>
18  );
19}

This works because navigation.location is only defined while a navigation is in flight. It holds the destination URL, so the component can derive the optimistic state from the search params the router is navigating to. When the navigation completes, navigation.location becomes undefined in the same render cycle that delivers the fresh loader props. The ternary falls through to the new server data automatically.

Key properties of this pattern:

• No local state: Nothing to sync, reset, or reconcile.
• Survives the pending phase: The optimistic value is read from the URL the router is navigating to, so it persists for the entire loader fetch.
• Self-cleaning: Once the navigation settles, the component naturally falls back to the new props.

useOptimistic applies a temporary state update that React automatically reverts once the underlying async operation settles. It’s suited for more complex optimistic transformations where the optimistic state isn’t a direct read from formData or the URL, for example, inserting a new item into a list.

1import { useOptimistic } from 'react';
2
3function ProductList({ products }: { products: Product[] }) {
4  const [optimisticProducts, addOptimistic] = useOptimistic(
5    products,
6    (state, newProduct: Product) => [...state, newProduct]
7  );
8
9  async function handleAdd(formData: FormData) {
10    const name = formData.get('name') as string;
11    addOptimistic({ id: 'temp', name }); // Immediate UI update
12    await createProduct(name);           // Actual server call
13  }
14
15  return (
16    <>
17      <form action={handleAdd}>
18        <input name="name" />
19        <button type="submit">Add</button>
20      </form>
21      <ul>
22        {optimisticProducts.map(p => (
23          <li key={p.id} style={{ opacity: p.id === 'temp' ? 0.5 : 1 }}>
24            {p.name}
25          </li>
26        ))}
27      </ul>
28    </>
29  );
30}

React Router treats errors from loaders and actions as a first-class route state. When a loader or action throws an error, React Router catches the error and renders the nearest ErrorBoundary export in the route hierarchy.

useRouteError accesses the thrown error inside an ErrorBoundary. isRouteErrorResponse distinguishes between Response-based errors (thrown via throw new Response(...) or data() with a non-2xx status in a loader or action) and unexpected exceptions. This behavior enables differentiated error UIs, for example, a styled 404 page vs. a generic error fallback.

1// routes/products.tsx
2import { useRouteError, isRouteErrorResponse } from "react-router";
3
4export function ErrorBoundary() {
5  const error = useRouteError();
6
7  if (isRouteErrorResponse(error)) {
8    return (
9      <div>
10        <h1>{error.status}</h1>
11        <p>{error.statusText}</p>
12      </div>
13    );
14  }
15
16  return <div>An unexpected error occurred.</div>;
17}

The sections above cover state that React Router manages as part of the routing and data lifecycle. What remains to complete the picture, is state that lives entirely on the client, managed by React’s own primitives. These are the built-in hooks and patterns for local component state, derived values, cross-component sharing, and integration with external stores.

The baseline primitive for synchronous, isolated state within a single component. Use the useState hook when exactly one component owns the state and you don’t need to share it.

1function Counter() {
2  const [count, setCount] = useState(0);
3  return <button onClick={() => setCount((c) => c + 1)}>{count}</button>;
4}

The useReducer hook is preferable over useState when state transitions are complex, interdependent, or benefit from explicit action semantics.

1type State = { count: number, step: number };
2type Action = { type: "increment" } | { type: "setStep", payload: number };
3
4function reducer(state: State, action: Action): State {
5  switch (action.type) {
6    case "increment":
7      return { ...state, count: state.count + state.step };
8    case "setStep":
9      return { ...state, step: action.payload };
10  }
11}
12
13function Counter() {
14  const [state, dispatch] = useReducer(reducer, { count: 0, step: 1 });
15  return (
16    <>
17      <p>Count: {state.count}</p>
18      <button onClick={() => dispatch({ type: "increment" })}>+</button>
19      <input
20        type="number"
21        value={state.step}
22        onChange={(e) => dispatch({ type: "setStep", payload: Number(e.target.value) })}
23      />
24    </>
25  );
26}

Derived state is any value you compute from existing state or props rather than store independently. It’s a pure function of other state and has no source of truth of its own.

Key rule: Don’t store derived values in useState. This practice creates a secondary source of truth and forces manual synchronization, which is a common source of bugs.

1// Bad: redundant state, sync required
2const [fullName, setFullName] = useState(`${firstName} ${lastName}`);
3
4// Good: computed inline, always in sync
5const fullName = `${firstName} ${lastName}`;

useMemo caches the result of an expensive computation and only recalculates it when one of its dependencies changes, preventing unnecessary recalculation on every render. Use this for expensive transformations, such as sorting, filtering, and aggregating, over arrays or objects.

When to use useMemo: For cheap computations, a plain variable in the render body is sufficient. Reserve useMemo for expensive computations or when referential stability is required (for example, as a dependency in useEffect or memo).

1// Plain variable: fine for cheap ops
2const fullName = `${firstName} ${lastName}`;
3
4// useMemo: justified for expensive ops or stable references
5const filteredItems = useMemo(() => largeList.filter((item) => item.active), [largeList]);

useCallback memoizes a function reference. Without it, every render creates a new function instance, which breaks referential equality checks in child components wrapped with memo.

1const handleDelete = useCallback((id: string) => {
2  setProducts((prev) => prev.filter((p) => p.id !== id));
3}, []); // stable reference — no unnecessary re-renders in React.memo children

When useCallback isn’t needed: If memo doesn’t wrap the receiving component, useCallback has no observable effect and only adds noise. Apply it specifically when passing callbacks to memoized components or as dependencies of other hooks (useEffect, useMemo) where referential stability matters.

Context propagates state through the React tree without prop drilling. It’s appropriate for state that changes infrequently and must be accessible across many components.

Good use cases: Locale, user preferences, and feature flags.

Poor use cases: High-frequency updates (for example, mouse position, real-time data), large state objects where many consumers only need a small slice.

1// preferences-context.tsx
2type PreferencesState = {
3  density: "compact" | "comfortable",
4  setDensity: (d: "compact" | "comfortable") => void,
5};
6const PreferencesContext = (createContext < PreferencesState) | (null > null);
7
8export function PreferencesProvider({ children }: { children: React.ReactNode }) {
9  const [density, setDensity] = (useState < "compact") | ("comfortable" > "comfortable");
10
11  return (
12    <PreferencesContext.Provider value={{ density, setDensity }}>
13      {children}
14    </PreferencesContext.Provider>
15  );
16}
17
18export function usePreferences() {
19  const ctx = useContext(PreferencesContext);
20  if (!ctx) {
21    throw new Error("usePreferences must be used within PreferencesProvider");
22  }
23  return ctx;
24}

1// Instead of one large context:
2<AppContext.Provider value={{ user, preferences, locale }} />
3
4// Split into focused contexts:
5<UserContext.Provider value={user} />
6<PreferencesContext.Provider value={preferences} />
7<LocaleContext.Provider value={locale} />

When a context holds multiple values but a consumer only needs one slice, splitting contexts isn’t always practical. Domain stores often have many fields and many consumers each needing different slices. The selector pattern addresses this demand by accepting a selector function and returning only the selected slice. Combined with useSyncExternalStore, subscriptions are per-slice: a consumer re-renders only when its slice changes.

The context holds a reference to an external store, not the state itself. The hook drives the subscription via useSyncExternalStore:

1const StoreLocatorContext = createContext<StoreApi<StoreLocatorState> | null>(null);
2
3export function useStoreLocator<T>(selector: (state: StoreLocatorState) => T): T {
4  const store = useContext(StoreLocatorContext);
5  if (!store) {
6    throw new Error('useStoreLocator must be used within StoreLocatorProvider');
7  }
8  const getSnapshot = useCallback(() => selector(store.getState()), [store, selector]);
9  return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
10}

Consumers call the hook once per slice. The badge re-renders only when isOpen flips. The form re-renders only when config changes:

1function StoreLocatorBadge() {
2  const isOpen = useStoreLocator((s) => s.isOpen);
3  const close = useStoreLocator((s) => s.close);
4  // ...
5}
6
7function StoreLocatorForm() {
8  const config = useStoreLocator((s) => s.config);
9  // ...
10}

useSyncExternalStore integrates state that lives outside the React tree—vanilla JavaScript objects, browser APIs, or custom event emitters. It is concurrent-mode safe and does not require a Provider.

1// store.ts
2type Listener = () => void;
3
4function createStore<T>(initialState: T) {
5  let state = initialState;
6  const listeners = new Set<Listener>();
7
8  return {
9    getSnapshot: () => state,
10    subscribe: (listener: Listener) => {
11      listeners.add(listener);
12      return () => listeners.delete(listener);
13    },
14    setState: (updater: (prev: T) => T) => {
15      state = updater(state);
16      listeners.forEach((fn) => fn());
17    },
18  };
19}
20
21export const cartStore = createStore({ items: [] as CartItem[] });

1// useCart.ts
2import { useSyncExternalStore } from "react";
3import { cartStore } from "./store";
4
5export function useCart() {
6  const state = useSyncExternalStore(cartStore.subscribe, cartStore.getSnapshot);
7
8  return {
9    items: state.items,
10    addItem: (item: CartItem) => cartStore.setState((s) => ({ items: [...s.items, item] })),
11  };
12}

Every component calling useCart() subscribes automatically. No Provider, no wrapping component required.

The same pattern makes any browser API reactive:

1// useOnlineStatus.ts
2const subscribe = (cb: () => void) => {
3  window.addEventListener("online", cb);
4  window.addEventListener("offline", cb);
5  return () => {
6    window.removeEventListener("online", cb);
7    window.removeEventListener("offline", cb);
8  };
9};
10
11export const useOnlineStatus = () =>
12  useSyncExternalStore(
13    subscribe,
14    () => navigator.onLine,
15    () => true, // server snapshot (SSR)
16  );

The same pattern applies to matchMedia, localStorage, BroadcastChannel, visibilitychange, and similar APIs.

getSnapshot must return a referentially stable value when state hasn’t changed. Returning a new object on every call causes an infinite render loop.

1// WRONG — new object reference on every call
2getSnapshot: () => ({ ...state });
3
4// CORRECT — same reference when state is unchanged
5getSnapshot: () => state;

If you need derived/selected state, cache the result inside the store or use useRef for memoization.

Reads a Promise directly inside a component and integrates with Suspense. Eliminates the need for useEffect-based data fetching and loading state management. For declarative loading patterns with use() and Suspense, see Loading States.

1import { use, Suspense } from "react";
2
3function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
4  const user = use(userPromise); // Suspends until resolved
5  return <p>{user.name}</p>;
6}
7
8function App() {
9  const userPromise = fetchUser(userId);
10  return (
11    <Suspense fallback={<Skeleton />}>
12      <UserProfile userPromise={userPromise} />
13    </Suspense>
14  );
15}

useTransition marks state updates as non-urgent, keeping the UI responsive during heavy re-renders.

1const [isPending, startTransition] = useTransition();
2
3function handleSearch(query: string) {
4  startTransition(() => {
5    setSearchResults(computeResults(query)); // Non-blocking update
6  });
7}

useDeferredValue defers the propagation of a rapidly changing value, similar to debouncing but integrated with React’s concurrent scheduler.

1const deferredQuery = useDeferredValue(searchQuery);
2// deferredQuery lags behind searchQuery during rapid input
3const results = useMemo(() => search(deferredQuery), [deferredQuery]);

useActionState manages the full lifecycle of an async action: pending status, return value, and error state. It replaces manual useState and useTransition wiring around actions. Listed here for completeness as a React primitive.

j

Announcements

Choose Your B2C Commerce Storefront Type

B2C Commerce

SCAPI

Storefront Next

Get Started

Storefront Next Release Notes

Managed Runtime Release Notes

Architecture and Core Concepts

Project Configuration and Build Tools

Data Fetching

Loading States

State Management

Basket Management

SCAPI Client

Content Caching

Storage and Sessions

Shopper Context

Server API Routes

UI Styling

Images

Static Assets

SEO and Metadata

AEO and GEO

Multisite Configuration

Internationalization

Adapters

Security Response Headers

Browser Compatibility

Quick Start: Create Storefront Next

Create an Environment in Business Manager

Connect an Existing Storefront to B2C Commerce

Build and Customize Storefront Next

Deploy and Manage Storefront Next on Managed Runtime

Preview, Test, and Debug Storefront Next

Optimize the Performance of Storefront Next

Track Storefront Next Activity with Analytics

Migrate from PWA Kit to Storefront Next

CLI Reference

Composable Storefront

Storefront Reference Architecture (SFRA)

Commerce Apps ISV Developer Guide

B2C Commerce Solutions

B2C Commerce Release Notes

B2C Commerce Reference Information

Ask the Community