react-router 8.4.0 → 8.5.0

package/docs/how-to/custom-fetch.md

@@ -0,0 +1,218 @@
+---
+title: Custom Fetch
+unstable: true
+---
+
+# Custom Fetch
+
+[MODES: framework]
+
+<docs-warning>This feature is experimental and may change in minor or patch releases. It is not supported in RSC Framework Mode.</docs-warning>
+
+The `unstable_fetch` prop on [`HydratedRouter`](../api/framework-routers/HydratedRouter) lets you customize the JavaScript-issued requests React Router makes for server loader/action data and lazy route discovery. Use it to add headers, customize fetch options, or apply a request policy based on the operation that initiated the request.
+
+This is a Framework Mode API. In Data Mode, you control fetching in your loaders/actions or through a [`dataStrategy`](./data-strategy#request-metadata-unstable).
+
+## Setup
+
+If you don't have an [`app/entry.client.tsx`](../api/framework-conventions/entry.client.tsx), reveal the default entry:
+
+```shellscript nonumber
+npx react-router reveal entry.client
+```
+
+Pass a custom implementation to `HydratedRouter`:
+
+```tsx filename=app/entry.client.tsx
+import { startTransition, StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+import {
+  HydratedRouter,
+  type unstable_RouterFetch,
+} from "react-router/dom";
+
+const customFetch: unstable_RouterFetch = (
+  request,
+  context,
+) => {
+  console.log(context.type, request.method, request.url);
+  return fetch(request);
+};
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <HydratedRouter unstable_fetch={customFetch} />
+    </StrictMode>,
+  );
+});
+```
+
+The callback receives a constructed `Request`, including its URL, headers, body, and abort signal, and must return a `Promise<Response>`. Pass that request to the browser's `fetch` to preserve those settings, including cancellation.
+
+`HydratedRouter` creates a singleton router and reads `unstable_fetch` only during initialization. Changing the prop later has no effect. If your implementation needs changing values such as authentication tokens, read current application state inside the callback instead of capturing values from a component render.
+
+## Request Context
+
+The [`unstable_RouterFetchContext`](https://api.reactrouter.com/v8/types/react-router.dom.unstable_RouterFetchContext.html) type is exported from `react-router/dom` and has the following shape:
+
+```ts
+import type { NavigationType } from "react-router";
+
+type unstable_RouterFetchContext =
+  | { type: "manifest" }
+  | {
+      type: "navigation";
+      fetcherKey: string | null;
+      navigationType: NavigationType;
+    }
+  | {
+      type: "initialization" | "fetcher" | "revalidation";
+      fetcherKey: string | null;
+      navigationType: null;
+    };
+```
+
+`type` identifies the operation that initiated the request:
+
+- `"manifest"`: Lazy route discovery requests. These have no `fetcherKey` or `navigationType`.
+- `"initialization"`: Data loading during router initialization, such as initial loader requests in API-only Mode.
+- `"navigation"`: Data requests initiated by a navigation, including action submissions and the subsequent loader revalidation.
+- `"fetcher"`: Requests initiated by a fetcher, including the loader revalidation after a fetcher action.
+- `"revalidation"`: Requests initiated by an explicit revalidation, such as `useRevalidator().revalidate()`.
+
+`fetcherKey` identifies the fetcher targeted by a data request, or is `null` for route loader/action requests. A fetcher reloaded as part of a navigation or explicit revalidation retains that initiating `type` and also includes its fetcher key. Fetchers reloaded after an initialization redirect likewise retain the `"initialization"` type and include their fetcher key.
+
+`navigationType` is `"PUSH"`, `"REPLACE"`, or `"POP"` for navigation-initiated data requests, including fetchers reloaded by that navigation. It is `null` for initialization, standalone fetcher operations, and explicit revalidation. This is the history action for the in-flight navigation, not the previously committed location.
+
+## Examples
+
+Each example below can be passed to `HydratedRouter` as its `unstable_fetch` prop.
+
+### Authentication and Custom Headers
+
+Read the current token at request time so token changes don't require replacing the callback:
+
+```ts
+import type { unstable_RouterFetch } from "react-router/dom";
+import { authStore } from "./auth";
+
+const customFetch: unstable_RouterFetch = (request) => {
+  let headers = new Headers(request.headers);
+  let token = authStore.getAccessToken();
+
+  if (token) {
+    headers.set("Authorization", `Bearer ${token}`);
+  }
+
+  headers.set("X-App-Version", "1.0");
+  return fetch(request, { headers });
+};
+```
+
+Here, `authStore` is your application's authentication store. Only send credentials to trusted origins. Adding custom headers to cross-origin requests may require a CORS preflight and corresponding server configuration.
+
+### Cross-Origin Credentials
+
+In [API-only Mode](../start/framework/rendering#using-a-separate-api-origin), use `unstable_apiServerOrigin` to configure a separate API origin. React Router applies that origin before calling your custom fetch, and also uses it for native data prefetches.
+
+The origin setting does not enable cross-origin cookies. If you need them, customize the credential policy for the trusted API origin:
+
+```ts
+import type { unstable_RouterFetch } from "react-router/dom";
+
+const customFetch: unstable_RouterFetch = (request) => {
+  let isApiRequest =
+    new URL(request.url).origin ===
+    "https://api.example.com";
+
+  return fetch(request, {
+    credentials: isApiRequest
+      ? "include"
+      : request.credentials,
+  });
+};
+```
+
+The API server must allow credentialed CORS requests from your client origin. Browser cookie policies still apply. Native data prefetches do not use this callback, so don't rely on it to configure their credentials.
+
+### Back/Forward Traversal Cache
+
+Use `navigationType` to prefer the browser's HTTP cache when navigating back or forward, while retaining the normal cache policy for other requests:
+
+```ts
+import type { unstable_RouterFetch } from "react-router/dom";
+
+const customFetch: unstable_RouterFetch = (
+  request,
+  context,
+) => {
+  let isTraversal =
+    import.meta.env.PROD &&
+    request.method === "GET" &&
+    context.type === "navigation" &&
+    context.navigationType === "POP";
+
+  return fetch(request, {
+    cache: isTraversal ? "force-cache" : "default",
+  });
+};
+```
+
+This example enables the policy in production only. It includes GET requests for fetchers reloaded by a back/forward navigation, but not standalone fetcher loads or explicit revalidations.
+
+The [`force-cache` policy](https://fetch.spec.whatwg.org/#concept-request-cache-mode) uses a matching HTTP cache entry even if it is stale, falling back to the network when no entry exists. Your server's responses must be cacheable; `Cache-Control: no-store` responses aren't stored.
+
+This is not a router-managed data cache. React Router still performs its request and response decoding, and this policy adds no mutation or authentication invalidation guarantees. Only use it when serving potentially stale data is appropriate for your application.
+
+### Retrying Safe Requests
+
+You can retry a safe GET after a network failure without retrying action submissions or canceled requests:
+
+```ts
+import type { unstable_RouterFetch } from "react-router/dom";
+
+const customFetch: unstable_RouterFetch = async (
+  request,
+) => {
+  if (request.method !== "GET") {
+    return fetch(request);
+  }
+
+  try {
+    return await fetch(request.clone());
+  } catch (error) {
+    if (
+      request.signal.aborted ||
+      (error instanceof Error &&
+        error.name === "AbortError")
+    ) {
+      throw error;
+    }
+
+    // Retry once, retaining the original abort signal.
+    return fetch(request);
+  }
+};
+```
+
+This assumes your GET endpoints are safe to repeat. It retries a rejected fetch, not HTTP error responses such as `500`. Don't automatically retry mutations: the server may have processed an action even when the client didn't receive its response.
+
+## Limitations
+
+### Requests Outside Custom Fetch
+
+Custom fetch does not intercept the initial document request, server-side loader execution, static assets, or fetches you write in your own application code, including in `clientLoader`/`clientAction`. Calls to their `serverLoader`/`serverAction` helpers do use custom fetch when they issue server data requests.
+
+Data prefetches from `<Link prefetch>`, `<NavLink prefetch>`, and [`PrefetchPageLinks`](../api/components/PrefetchPageLinks) use native `<link rel="prefetch">` elements and bypass custom fetch. If a request requires custom headers or other transformations, use `prefetch="none"` on links and avoid rendering `PrefetchPageLinks` for those routes.
+
+### Inspecting Request Bodies
+
+If you need a form field such as `intent` to choose request headers, read it from `await request.clone().formData()` for form-encoded submissions, then send the original request. Reading `request.formData()` directly consumes the body so it can't subsequently be sent unchanged.
+
+Only parse bodies with a compatible encoding. Cloning and reading a body can buffer data, so avoid doing this unnecessarily, especially for large file uploads. Adding headers or changing fetch options does not require reading the body.
+
+### Response Compatibility
+
+Return the response from `fetch` unchanged. You can inspect its status and headers, but you should not consume its body or try to decode, modify, or re-encode it. React Router handles response decoding and expects its manifest/data protocol, including Turbo Stream-encoded loader/action data.

package/docs/how-to/data-strategy.md

@@ -23,7 +23,9 @@ A custom `dataStrategy` receives the `loader`/`action` arguments (`request`, `pa
 
 - `matches`: An array of `DataStrategyMatch` instances for the routes matched by the current `request`
 - `runClientMiddleware`: A helper function to run the middleware for the matched routes
-- `fetcherKey`: The fetcher key if this is for a fetcher request and not a navigation
+- `fetcherKey`: The key of the fetcher targeted by this execution, or `null` for route loader/action executions. Fetchers reloaded by a navigation or explicit revalidation also provide their key.
+- `unstable_initiator`: The operation that initiated this execution (see [Request Metadata](#request-metadata-unstable))
+- `unstable_navigationType`: The history action for a navigation-initiated execution, or `null` for other executions
 
 A `DataStrategyMatch` is a normal route match plus a few additional fields:
 
@@ -77,6 +79,26 @@ interface DataStrategyResult {
 }
 ```
 
+### Request Metadata (unstable)
+
+<docs-warning>`unstable_initiator` and `unstable_navigationType` are experimental and may change in minor or patch releases.</docs-warning>
+
+`unstable_initiator` identifies why the data strategy is running:
+
+- `"initialization"`: Initial router data loading
+- `"navigation"`: A navigation, including action submissions and subsequent loader revalidation
+- `"fetcher"`: A fetcher operation, including loader revalidation after a fetcher action
+- `"revalidation"`: Explicit revalidation, such as `useRevalidator().revalidate()`
+- `"static"`: Execution by `createStaticHandler` on the server
+
+Requests that reload fetchers during a navigation or explicit revalidation retain that initiator while providing the targeted `fetcherKey`. Don't use `fetcherKey` alone to determine what initiated the execution.
+
+`unstable_navigationType` is `"PUSH"`, `"REPLACE"`, or `"POP"` for navigation-initiated executions, including fetchers reloaded by that navigation. It is `null` for initialization, standalone fetcher operations, explicit revalidation, and static handler executions. It describes the in-flight navigation rather than the previously committed location.
+
+You can use this metadata to choose a loading or caching policy. For example, a Data Mode `dataStrategy` can distinguish back/forward navigations with `unstable_initiator === "navigation" && unstable_navigationType === "POP"`. Your strategy remains responsible for executing the appropriate handlers and returning their results.
+
+Framework Mode exposes equivalent request metadata through [`unstable_fetch`](./custom-fetch#request-context), which customizes server requests without replacing loader/action execution.
+
 ### Calling Route Middleware
 
 If you are using `middleware` on your routes, you need to leverage the `callClientMiddleware` helper function to execute `middleware` around your handlers:

package/docs/how-to/middleware.md

@@ -635,6 +635,7 @@ export async function loader({
 [server-client]: #server-vs-client-middleware
 [framework-action]: ../start/framework/route-module#action
 [framework-loader]: ../start/framework/route-module#loader
+[getloadcontext]: ../api/other-api/adapter#react-routerexpress
 [datastrategy]: ../api/data-routers/createBrowserRouter#optsdatastrategy
 [cms-redirect]: #cms-redirect-on-404
 [createContext]: ../api/utils/createContext

package/docs/how-to/optimize-revalidation.md

@@ -25,10 +25,10 @@ Prefer targeting a specific action or navigation, and fall back to
 The default behavior differs between Framework and Data Modes:
 
 - **Framework Mode with SSR**
-  - Defaults to opt-out behavior - active loaders are revalidated on navigations and successful submissions ([`Link`][link], [`Form`][form], [`fetcher.submit`](fetcher-submit))
+  - Defaults to opt-out behavior - active loaders are revalidated on navigations and successful submissions ([`Link`][link], [`Form`][form], [`fetcher.submit`][use-fetcher])
   - Failed submissions returning a 4xx/5xx status do not trigger revalidations by default
 - **Framework "SPA Mode" and Data Mode**
-  - Defaults to opt-out behavior on successful submissions - active loaders are revalidated on successful submissions ([`Form`][form], [`fetcher.submit`])
+  - Defaults to opt-out behavior on successful submissions - active loaders are revalidated on successful submissions ([`Form`][form], [`fetcher.submit`][use-fetcher])
     - Failed submissions returning a 4xx/5xx status do not trigger revalidations by default
   - Defaults to opt-in behavior for GET navigations ([`Link`][link]) - active loaders are only revalidated if their dynamic params changed, or if any search params changed
     - A GET navigation to the _exact_ same URL is treated like a page refresh and all loaders are revalidated.

package/docs/how-to/pre-rendering.md

@@ -84,10 +84,11 @@ export default {
 
 ## Pre-Rendering with/without a Runtime Server
 
-Pre-Rendering can be used in two ways based on the `ssr` config value:
+Pre-Rendering can be used with these `ssr` config values:
 
 - Alongside a runtime SSR server with `ssr:true` (the default value)
 - Deployed to a static file server with `ssr:false`
+- Alongside a runtime API server with `ssr:"unstable_api-only"` (experimental)
 
 ### Pre-rendering with `ssr:true`
 
@@ -223,3 +224,24 @@ When pre-rendering with `ssr:false`, React Router will error at build time if yo
   - If you are using a `loader` on a pre-rendered route that has child routes, you will need to make sure the parent `loaderData` can be determined at run-time properly by either:
     - Pre-rendering all child routes so that the parent `loader` can be called at build-time for each child route path and rendered into a `.data` file, or
     - Use a `clientLoader` on the parent that can be called at run-time for non-pre-rendered child paths
+
+### Pre-rendering with API-only Mode (unstable)
+
+<docs-warning>API-only Mode is experimental and may change in minor or patch releases. It is not supported in RSC Framework Mode.</docs-warning>
+
+Use `ssr: "unstable_api-only"` with `prerender` to generate documents at build time while keeping a runtime server for loaders, actions, and route discovery:
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: "unstable_api-only",
+  prerender: ["/"],
+} satisfies Config;
+```
+
+Document generation follows the same behavior as `ssr:false`: selected paths produce HTML and `.data` files, and other paths use a SPA fallback. The fallback is `__spa-fallback.html` when `/` is prerendered, or `index.html` otherwise.
+
+Prerendered pages hydrate using their build-time data. Pages using the fallback fetch server loader data during initialization. Server loaders and actions are available on all routes, including those outside the prerender list, and normal loader revalidation remains enabled.
+
+See [API-only Mode](../start/framework/rendering#api-only-mode-unstable) for deployment routing and configuring a separate API origin.

package/docs/how-to/route-discovery.md

@@ -0,0 +1,145 @@
+---
+title: Application-Controlled Route Discovery
+unstable: true
+---
+
+# Application-Controlled Route Discovery
+
+[MODES: framework]
+
+<docs-warning>This API is unstable and may change without a major release. It supports conventional Framework Mode; RSC modes are not supported.</docs-warning>
+
+Enable the future flag in `react-router.config.ts`:
+
+```ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  future: { unstable_customRouteDiscovery: true },
+} satisfies Config;
+```
+
+Without this flag, React Router keeps its existing discovery implementation and the hook is unavailable. The flag supports conventional Framework Mode only.
+
+Keep `routeDiscovery.mode: "lazy"` (the default for SSR) and use `unstable_useRouteDiscovery` to choose when to discover destinations or load the complete route manifest.
+
+```tsx
+let { state, discoverRoutes, loadAllRoutes } =
+  unstable_useRouteDiscovery({
+    onManifestMismatch: async (event) => {
+      // Handle mismatch, potentially by loading the entire manifest
+      await loadAllRoutes();
+    },
+  });
+
+// state: "partial" | "loading" | "complete"
+
+// Eagerly discover specific paths
+let result = await discoverRoutes(paths);
+```
+
+## Imperative Route Discovery
+
+You can control route discovery through `discoverRoutes()` without having to render links/forms on the page - this allows you to eagerly discover routes that are not directly linked from the current UI. Note that discovery only loads route metadata - it does not navigate, run loaders/actions, or prefetch route modules/stylesheets. Paths are batched within the manifest request URL limit and previously discovered paths are skipped.
+
+`discoverRoutes(paths, { signal })` accepts application-root paths beginning with `/`. React Router applies the configured `basename` and ignores query strings and hashes. Relative paths and external URLs are not supported.
+
+The result is `{ type: "success" }`, `{ type: "version-mismatch" }`, or `{ type: "aborted" }`. Success means the discovery operation completed successfully; it does not guarantee that a request was sent or that each pathname matches a route. Cached paths need no request, and a concurrent full-manifest load can supersede an incremental request failure. Unrecovered request failures and unrelated handler errors reject. Imperative mismatches do not automatically trigger a reload.
+
+For example, the cart's checkout link automatically discovers the shipping route. Use the hook to discover later checkout steps when the cart mounts, even though those steps aren't linked from the cart:
+
+```tsx
+import { useEffect } from "react";
+import {
+  Link,
+  unstable_useRouteDiscovery,
+} from "react-router";
+
+function Cart() {
+  let { discoverRoutes } = unstable_useRouteDiscovery();
+
+  useEffect(() => {
+    let controller = new AbortController();
+
+    discoverRoutes(
+      ["/checkout/billing", "/checkout/review"],
+      { signal: controller.signal },
+    ).catch(console.error);
+
+    return () => controller.abort();
+  }, [discoverRoutes]);
+
+  return (
+    <>
+      {/* Render cart items and totals here. */}
+      <Link to="/checkout/shipping">
+        Proceed to checkout
+      </Link>
+    </>
+  );
+}
+```
+
+## Completing discovery
+
+`loadAllRoutes()` loads the running client's versioned manifest asset to complete its route tree, even if that client is stale. This merges all missing routes into the running router and thus prevents further incremental discovery. The exposed `version` remains the version of the running client. With `routeDiscovery.mode: "initial"`, SPA Mode, or development's full manifest, the state is already `complete` and the operations are successful no-ops.
+
+The shared `state` moves from `partial` to `loading` to `complete`. Concurrent calls share a load, and calls after completion resolve immediately. Failures reject and return the state to `partial`; applications can catch the error and choose whether to reload.
+
+Retain the client's versioned manifest **and its referenced assets** for as long as that client is supported. Server routing and loader/action contracts must also remain compatible. Loading build A's manifest does not make an incompatible build B backend safe for build A's client.
+
+## Handling manifest mismatches
+
+You can provide custom handling for manifest version mismatches to avoid hard reloads, giving you a chance to complete the route tree, or cancel the navigation and provide a prompt for the user to reload (see below). A mismatch indicates different versions, not which version is newer.
+
+```tsx
+unstable_useRouteDiscovery({
+  onManifestMismatch: async (event) => {
+    await event.loadAllRoutes();
+  },
+});
+```
+
+After mismatch handlers settle, surviving operations continue only if the tree is complete. Otherwise navigations and fetchers are canceled and their pending state settles. Canceling a navigation also cancels any pending revalidation - both return to idle and the current page and data remain in place without another loader pass. Similarly, interrupted fetcher loads settle with their existing data. If an action already changed server data, the displayed data may remain stale until a later navigation or explicit revalidation.
+
+Router-managed Back/Forward cancellations restore the prior history position. Additional browser Back/Forward presses during restoration can leave the URL and rendered route out of sync or navigate to another entry; preserving the current screen is not guaranteed in that case.
+
+Full-manifest load failures remain catchable and do not render route error boundaries, whether the handler calls `event.loadAllRoutes()` or the function returned by the hook. Uncaught full-load failures are reported through `<HydratedRouter onError>` or `console.error`, and the incomplete operation is canceled. Unrelated handler errors follow normal discovery error handling.
+
+## Temporary overrides
+
+Custom mismatch handlers override built-in recovery. Calling the hook without a handler does not override anything. Removing the last custom mismatch handler restores automatic recovery.
+
+Call `event.defaultBehavior()` to explicitly run built-in recovery: eager mismatches warn, navigation mismatches reload the destination, fetcher mismatches reload the current document, and imperative mismatches return without reloading. Repeated calls for one shared mismatch event reuse the same promise. It does not invoke other custom handlers or stop their propagation.
+
+```tsx
+unstable_useRouteDiscovery({
+  async onManifestMismatch(event) {
+    if (hasUnsavedChanges) {
+      event.stopPropagation();
+      setShowReloadDialog(true);
+      return;
+    }
+    await event.defaultBehavior();
+  },
+});
+```
+
+Custom handlers run in reverse registration order, with each awaited before the next. `stopPropagation()` prevents earlier handlers from running; it does not complete discovery or allow an operation to continue against an incomplete tree.
+
+```tsx
+unstable_useRouteDiscovery({
+  onManifestMismatch(event) {
+    if (hasUnsavedChanges) {
+      event.stopPropagation();
+      setShowReloadDialog(true);
+    }
+  },
+});
+```
+
+An editor mounted after a root recovery handler can use this to preserve a draft. Unmounting removes its registration and reveals earlier handlers. Callback updates preserve registration priority. This is registration order, not a guarantee that the deepest component runs first.
+
+Eager discovery waits for the initialized route tree to commit so a root handler can intercept the first request. It does not wait for every suspended descendant or guarantee an idle main thread. Discovery needed before handlers can mount retains normal lazy behavior.
+
+Without mismatch handlers, existing automatic recovery for eager/navigation/fetcher discovery remains unchanged. Deployment polling and staleness policy remain application-owned.

package/docs/how-to/spa.md

@@ -22,6 +22,8 @@ Typical Single Page apps send a mostly blank `index.html` template with little m
 
 <docs-info>SPA Mode is a special form of "Pre-Rendering" that allows you to serve all paths in your application from the same HTML file. Please refer to the [Pre-Rendering](./pre-rendering) guide if you want to do more extensive pre-rendering.</docs-info>
 
+<docs-info>If you want a SPA frontend backed by React Router server loaders and actions, see experimental [API-only Mode](../start/framework/rendering#api-only-mode-unstable).</docs-info>
+
 ## 1. Disable Runtime Server Rendering
 
 Server rendering is enabled by default. Set the `ssr` flag to `false` in `react-router.config.ts` to disable it.

package/docs/how-to/view-transitions.md

@@ -4,16 +4,78 @@ title: View Transitions
 
 # View Transitions
 
-[MODES: framework, data]
+[MODES: framework, data, declarative]
 
 <br/>
 <br/>
 
-Enable smooth animations between page transitions in your React Router applications using the [View Transitions API][view-transitions-api]. This feature allows you to create seamless visual transitions during client-side navigation.
+Use React's [`<ViewTransition>`][react-view-transition] component to animate client-side navigations. This requires React and React DOM 19.3 or later.
 
-## Basic View Transition
+<docs-warning>
 
-### 1. Enable view transitions on navigation
+React Router's `viewTransition` props/options, `useViewTransitionState` hook, and `NavLink`'s `isTransitioning` render prop and `transitioning` class are deprecated in favor of React's `<ViewTransition>` component. The existing APIs continue to work, including with older React versions.
+
+</docs-warning>
+
+## Navigation View Transitions with React
+
+Wrap the outlet in a persistent `<ViewTransition>` boundary in a shared layout route. In Framework Mode, this can be your root route's default export; in Data and Declarative modes, use it as the component for a parent route with children:
+
+```tsx
+import { ViewTransition } from "react";
+import { Link, Outlet } from "react-router";
+
+export default function PageLayout() {
+  return (
+    <>
+      <nav>
+        <Link to="/">Home</Link>
+        <Link to="/about">About</Link>
+      </nav>
+      <ViewTransition>
+        <main>
+          <Outlet />
+        </main>
+      </ViewTransition>
+    </>
+  );
+}
+```
+
+Navigations that update the outlet cross-fade its contents. Keep the boundary mounted across navigations; you don't need to key it by location or remount the route tree. The navigation stays outside the animated region. Other updates inside the boundary can also animate when they run in a React Transition.
+
+React Router wraps router state updates in [`React.startTransition`][start-transition] by default, which lets React activate `<ViewTransition>` without additional configuration. React Transitions must remain enabled for navigation view transitions to work: do not set `useTransitions={false}` on your router.
+
+This applies to navigations from `<Link>`, `<NavLink>`, and `<Form>`, as well as programmatic navigation with `useNavigate` and `useSubmit`. No additional `startTransition` wrapper is needed.
+
+### Migrating from React Router's view transitions
+
+- Remove `viewTransition` from `<Link>`, `<NavLink>`, and `<Form>`, and remove `viewTransition: true` from navigation/submission options. React coordinates `document.startViewTransition()` itself; enabling both implementations can interrupt animations.
+- Replace `useViewTransitionState`, `isTransitioning`, and `.transitioning` styles with React's [View Transition classes][react-view-transition-classes]. Those router APIs only track the legacy transitions.
+- For shared elements such as an image moving from a list to a detail route, wrap each side in `<ViewTransition name="...">` with the same unique name. See React's [shared element example][react-shared-elements].
+- Keep React Transitions enabled. `useTransitions={false}` and synchronous updates such as `flushSync` can prevent React's animations.
+
+React's component is not a drop-in replacement for every legacy animation. In particular, React [skips view transitions for synchronous updates from `popstate`][react-router-transitions], so browser Back/Forward navigations may not animate. Browsers without View Transitions support still navigate normally.
+
+Respect reduced-motion preferences when adding animations:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation: none !important;
+  }
+}
+```
+
+## Legacy View Transitions (Deprecated)
+
+The following examples document the deprecated APIs for existing applications. These APIs are available in Framework and Data modes.
+
+### Basic View Transition
+
+#### 1. Enable view transitions on navigation
 
 The simplest way to enable view transitions is by adding the `viewTransition` prop to your `Link`, `NavLink`, or `Form` components. This automatically wraps the navigation update in `document.startViewTransition()`.
 
@@ -25,7 +87,7 @@ The simplest way to enable view transitions is by adding the `viewTransition` pr
 
 Without any additional CSS, this provides a basic cross-fade animation between pages.
 
-### 2. Enable view transitions with programmatic navigation
+#### 2. Enable view transitions with programmatic navigation
 
 When using programmatic navigation with the `useNavigate` hook, you can enable view transitions by passing the `viewTransition: true` option:
 
@@ -51,11 +113,11 @@ This provides the same cross-fade animation as using the `viewTransition` prop o
 
 For more information on using the View Transitions API, please refer to the ["Smooth transitions with the View Transition API" guide][view-transitions-guide] from the Google Chrome team.
 
-## Image Gallery Example
+### Image Gallery Example
 
 Let's build an image gallery that demonstrates how to trigger and use view transitions. We'll create a list of images that expand into a detail view with smooth animations.
 
-### 1. Create the image gallery route
+#### 1. Create the image gallery route
 
 ```tsx filename=routes/image-gallery.tsx
 import { NavLink } from "react-router";
@@ -91,7 +153,7 @@ export default function ImageGalleryRoute() {
 }
 ```
 
-### 2. Add transition styles
+#### 2. Add transition styles
 
 Define view transition names and animations for elements that should transition smoothly between routes.
 
@@ -127,7 +189,7 @@ Define view transition names and animations for elements that should transition
 }
 ```
 
-### 3. Create the image detail route
+#### 3. Create the image detail route
 
 The detail view needs to use the same view transition names to create a seamless animation.
 
@@ -151,7 +213,7 @@ export default function ImageDetailsRoute({
 }
 ```
 
-### 4. Add matching transition styles for the detail view
+#### 4. Add matching transition styles for the detail view
 
 ```css filename=app.css
 /* Match transition names from the list view */
@@ -169,11 +231,11 @@ export default function ImageDetailsRoute({
 }
 ```
 
-## Advanced Usage
+### Advanced Usage
 
 You can control view transitions more precisely using either render props or the `useViewTransitionState` hook.
 
-### 1. Using render props
+#### 1. Using render props
 
 ```tsx filename=routes/image-gallery.tsx
 <NavLink to={`/image/${idx}`} viewTransition>
@@ -201,7 +263,7 @@ You can control view transitions more precisely using either render props or the
 </NavLink>
 ```
 
-### 2. Using the `useViewTransitionState` hook
+#### 2. Using the `useViewTransitionState` hook
 
 ```tsx filename=routes/image-gallery.tsx
 function NavImage(props: { src: string; idx: number }) {
@@ -234,4 +296,9 @@ function NavImage(props: { src: string; idx: number }) {
 ```
 
 [view-transitions-api]: https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition
+[react-view-transition]: https://react.dev/reference/react/ViewTransition
+[start-transition]: https://react.dev/reference/react/startTransition
+[react-view-transition-classes]: https://react.dev/reference/react/ViewTransition#view-transition-class
+[react-shared-elements]: https://react.dev/reference/react/ViewTransition#animating-a-shared-element
+[react-router-transitions]: https://react.dev/reference/react/ViewTransition#building-view-transition-enabled-routers
 [view-transitions-guide]: https://developer.chrome.com/docs/web-platform/view-transitions