Element View Transition API

[ViewableGravy]

Summary

I wanted to create a document/discussion for how tanstack router might implement an API to support element level view transitions. The motivation behind this is the recent implementation and addition of this behind a flag in chrome 140, and the rationale that supporting element transitions in a routing library seems like an extremely reasonable place to do so, since we are often only swapping out portions of the application, and not necessarily the entire page.

This lends well to element transitions because we can simply animate the lowest non-replacing router matches children, allowing sections of a page to be animated while keeping the layout of the page static if it is not being replaced.

This proposal defines a rough, opt-in API surface for route-level transitions that integrates naturally with TanStack’s existing patterns, while enabling full use of Chrome’s new element-based transitions.

Note: This discussion is mostly relating to API design and not implementation details at this stage.
Disclaimer: AI was used in improving the writing of this proposal
View Transitions API.

Motivation

View transitions currently solve animation between pages, but at a cost. Currently, a document view transition overlays the entire document with the transition layer, which is then animated. this causes the entire page to be blocked from interaction while it is animating.

The element level transition API solves this by providing the animation at an element level (or in the router case, a match/outlet level). This allows us to animate sub-trees of the dom, while keeping layout related content such as headers, footers, etc, that exist across routes to remain interactive and opt out of animations.

For route-based applications, the most logical boundary to animate is the outlet of a route that remains mounted during navigation.

Proposed Additions

transitionComponent Route Option

const route = createFileRoute('/dashboard')({
  component: RouteComponent,
  transitionComponent: 'div',
});

transitionComponent accepts either:

• A string representing an HTML element (e.g. 'div', 'section', etc.)
• A custom React component (which may accept props or not, this will be discussed in the hook example).

If present, this component should wrap the child outlet of the route. This defines the transition boundary for its child routes.

💡This differs from pendingComponent and errorComponent, which wrap the route itself. In this case, the route provides a transition boundary for its children, not for itself. This is intentional — when a route is unmounted, it cannot animate its own exit, as the incoming route will (likely) not share a transition name/id, and would potentially define it's own transition/component/etc. Therefore, the logical approach is for a route to offer a transition context to its children rather than expect one.

From a type-level perspective, I would expect this to only exist on non-leaf routes, as it applies to it's children, and lead nodes do not have children

I do recognise that this could be confusing for a user, as it behaves differently to other functionality, but it seems reasonable in this case

Route.useRegisterTransition Hook, Component or HOC

Since transitionComponent cannot (should not) receive props other than children (consistent with other route components), an approach to creating a transitionComponent would be required. There are a few options that come to mind

Hook Approach with children prop

This approach is a hybrid of prop injection (children prop is easy to type manually) while relying on a hook to provide an inferred
ref callback.

function LayoutTransitionWrapper({ children }) {
  const registerTransitionComponent = Route.useRegisterTransition();

  return (
    <div ref={registerTransitionComponent} className="layout-transition">
      {children}
    </div>
  );
}

Hook Approach with Outlet (or TransitionOutlet)

This approach doesn't require any types being manually defined, and does not inject props, but introduces two new concepts for registering an outlet which seems heavy handed (although better than injecting props)

function LayoutTransitionWrapper() {
  const registerTransitionComponent = Route.useRegisterTransition();

  return (
    <div ref={registerTransitionComponent} className="layout-transition">
      <TransitionOutlet />
    </div>
  );
}

HOC Approach

This approach would infer the types for ref and children (as well as creating a forward ref in older react versions) by using a HOC.

const TransitionComponent = createTransitionComponent(({ children, ref }) => (
  <div ref={ref} className="layout-transition">
    {children}
  </div>;
));

Suggestion

Personally I am leaning to createTransitionComponent as it provides the least new features specifically for view transitions, while inferring all types. It also allows us to avoid manually creating a ForwardRef if the react version does not support it. The other options feel "clunky" in one way or another in my opinion

Global Default Option: mode

Extend the defaultViewTransition configuration in createRouter with a mode field:

const router = createRouter({
  routeTree,
  defaultViewTransition: {
    mode: 'element' | 'document',
  },
});

"element": Use the new element transition model. If a route doesn’t define transitionComponent, a <div> will be used automatically.
"document": Maintain existing document-level transitions (current behavior).

This provides a clean global opt-in without changing existing projects.

Behavior Summary

• Opt-in model: Controlled globally via defaultViewTransition.mode. Routes may add transitionComponent individually if desired.
• Default wrapper: When mode: "element" is used and no component is defined, a <div> automatically wraps the outlet.
• Ref-based registration: Route.useRegisterTransition() returns a ref callback for the transition element.
• Transition boundary: The element wraps the route’s outlet, animating its child transitions.
• Browser fallback: Gracefully no-ops if document.startViewTransition is unsupported.
• CSS control: Users provide their own view-transition-* CSS for animations.

Example Usage

const DashboardTransition = () => {
  const register = Route.useRegisterTransition();

  return (
    <section ref={register} className="dashboard-layout">
      <Outlet />
    </section>
  );
};

// with children /dashboard/settings and /dashboard/
export const Route = createFileRoute('/dashboard')({
  component: DashboardComponent,
  transitionComponent: DashboardTransition,
});

// define a global element transition
const router = createRouter({
  routeTree: Route,
  defaultViewTransition: {
    mode: 'element',
  },
});

In this example:

1. The /dashboard route stays mounted across navigations.
2. Its transitionComponent provides a transition boundary for its child routes.
3. Navigating between /dashboard → /dashboard/settings animates within that section.

Additional Notes

Async loaders:
No special handling needed — transitions start once routes are ready to render, consistent with current behavior.

History / scroll restoration:
Unaffected. Standard router behavior continues to apply.

Nested transitions:
If multiple transition elements exist in nested routes, the browser’s View Transition API should handle coordination automatically (needs confirmation through testing).

Non-supporting browsers:
Detection and fallback to no-op at runtime.

Summary

This proposal introduces:

• A composable API for element-level view transitions.
• A new transitionComponent option for routes.
• A simple useRegisterTransition hook for registering DOM nodes.
• A global mode toggle for "element" or "document" transitions.
• It stays consistent with TanStack Router’s design philosophy — declarative, headless, and flexible — while enabling modern, platform-native navigation transitions.

[ViewableGravy]

Just coming back to this as I've thought about this a lot since my initial proposal.

This entire problem may just be solved by reacts ViewTransition component. That's not a global solution obviously, but at least in react, I suspect that you will be able to do something like

<ViewTransition>
  <Outlet />
</ViewTransition>

And this will sort of just work. The downside is that you are forced into the transition with this approach, whereas with a router level approach, the transition becomes optional and something you can provide as an argument on navigation.

I still suspect that providing some kind of argument on the route which defines the transition, and then having the outlet render that transition component would make the most sense to be framework agnostic and hoist the handling to the router, but I'm not sure how reasonable my above suggestions are for this.