<ViewTransition> migration path for directional page transitions (transition types + back/forward)

[stvrhm]

8.5 deprecates the router's view transition APIs in favor of React's <ViewTransition> (#15493). Following the migration guide, the cross-fade case works. But there's no migration path yet for directional page transitions, and we'd like one before the legacy API goes away in v9.

Repro: https://stackblitz.com/edit/vitejs-vite-fhmxctzv (React 19.3, react-router 8.5.0, data router, Chromium). Open the preview in its own tab; an in-app guide walks through 5 scenarios and checks each result.

Use case

App-like, mobile-first site (also embedded in native WebViews) with directional full-page transitions:

• slide forward on PUSH
• slide backward on back (browser back button, navigate(-1), in-app back buttons)
• no router animation when the browser already animated a swipe-back gesture (hasUAVisualTransition)

Today we build this on the legacy viewTransition option plus document.startViewTransition types.

Why current APIs are insufficient

With a persistent <ViewTransition update={{ forward: 'forward', backward: 'backward', default: 'auto' }}> around <Outlet>:

1. Transition types don't reach the page swap. In a data router, startTransition(() => { addTransitionType('forward'); navigate(to) }) only works when the navigation resolves synchronously (no loader, no lazy). Otherwise the router commits navigation.state = "loading" inside our transition and the new page later in a transition without types, so the page swap runs with types: null (repro scenarios 1 vs 3). In framework mode this happens for every navigation, even without a loader (see comment below). If the layout re-renders on navigation state (e.g. useNavigation() for a global loading indicator), the loading commit even starts its own view transition over unchanged content, which gets the types (scenario 2; see <ViewTransition>: the router's "loading" commit starts an extra view transition that takes the transition types and delays the page swap #15670).
2. Back/forward can't carry a direction (scenarios 4 and 5). POP navigations that commit asynchronously animate, but without types, so there's no way to tell backward from forward. In a data router, POP navigations to routes without loaders don't animate at all, because React renders transitions started in a popstate event synchronously (as the guide notes). In framework mode they do animate, still without types.
3. UA gestures: there is no documented way to skip the router-driven transition when hasUAVisualTransition is true.

Possible API

• navigate(to, { transitionTypes: ['forward'] }), <Link transitionTypes={[...]}>, <Form transitionTypes>: the router calls addTransitionType inside the transition that commits the new location (not the loading one).
• A router-level hook for POP, e.g. getTransitionTypes({ currentLocation, nextLocation, historyAction, delta, hasUAVisualTransition }) => string[] | false. It covers back/forward direction and lets apps opt out on UA gestures (false).
• Make POP updates eligible for view transitions independent of loaders. For example, commit POP navigations in a non-synchronous transition when a <ViewTransition> boundary is present, or document how a router can follow React's "View Transition enabled router" guidance.

Happy to help test an unstable_ implementation.

[stvrhm]

Update: same repro in framework mode (ssr: true, route modules, server loader on /slow): https://stackblitz.com/edit/github-ov7fjxvh

Framework mode always commits navigation.state = "loading" first, even for routes without a loader (route discovery, route module, .data), and React starts a view transition for that commit. So addTransitionType never reaches the commit that swaps the page:

• With types attached, the unchanged current page slides out and back in.
• The page swap then cross-fades with types: null, and only after the first view transition has finished.

#	Scenario	Data mode	Framework mode
1	addTransitionType('forward') + navigate(), no loader	✅ slides	❌ two VTs, page swap has types null
2	Layout with useNavigation(), <Link> to route with loader	❌ two VTs	❌ two VTs
3	addTransitionType('forward') + navigate(), with loader	❌ page swap has types null	❌ two VTs, page swap has types null
4	addTransitionType('backward') + navigate(-1)	❌ types null	❌ types null
5	history.back(), no loader	no VT (React renders popstate transitions synchronously)	✅ cross-fade, types null

The results are the same with react-router dev, a production build, and routeDiscovery: { mode: "initial" }. The counts are measured with 600 ms animations and a 300 ms loader; with default animations, a loader route can show a third view transition, because route discovery emits a second loading state. I tested in Chromium only.

So in framework mode there is currently no way to give a navigation a direction with <ViewTransition>. A router-level transitionTypes option (or similar) seems to be the only way.