Skip to content

View Transitions in a static Next.js site

Page transitions with React's ViewTransition on a static export: an anchored header, enter and exit classes, reduced motion, and where it does nothing.

· Updated · 3 min read

The Lumora sign-in Lab example, a login card over a night sky, which uses a circular View Transition for its theme switch

React's <ViewTransition> can animate page changes in an App Router site with one wrapper and a short block of CSS. On my static export it lives in a single file, template.tsx, and browsers without view transitions swap the page instantly.

This post shows what I wrote, why the header stays put, and the rules in React's documentation that matter for accessibility and for back-button navigation.

The wrapper#

A Next.js template.tsx remounts on every navigation, which is exactly the trigger the component needs. This is the whole file:

"use client";

import { ViewTransition, type ReactNode } from "react";

export default function Template({ children }: { children: ReactNode }) {
  return (
    <ViewTransition enter="page-enter" exit="page-exit" default="none">
      {children}
    </ViewTransition>
  );
}

enter and exit are CSS class names that React attaches to the transition. default="none" matters: the React docs say that with default set to "none", all other triggers are off unless you list them, so only the page entering and leaving animates and not every update inside it.

React calls startViewTransition itself, and its docs say you should never call it yourself for updates React manages. Only updates wrapped in a transition, a <Suspense> boundary or useDeferredValue activate a <ViewTransition>, which is how a normal route change qualifies.

The CSS#

The animation is written against the names React generates:

#site-header {
  view-transition-name: site-header;
}
::view-transition {
  pointer-events: none;
  background: #050506;
}
::view-transition-old(.page-exit) {
  animation: page-exit 300ms cubic-bezier(0.55, 0, 1, 0.45) both;
}
::view-transition-new(.page-enter) {
  animation: page-enter 620ms cubic-bezier(0.16, 1, 0.3, 1) 220ms both;
}
@keyframes page-exit {
  to {
    opacity: 0;
    translate: 0 -3vh;
    scale: 0.985;
  }
}
@keyframes page-enter {
  from {
    opacity: 0;
    translate: 0 6vh;
  }
  to {
    opacity: 1;
    translate: 0 0;
  }
}

Three choices are worth explaining.

The header gets its own name. A view-transition-name on #site-header pulls it out of the page snapshot, so it stays in place while the page underneath leaves and arrives. Without it the whole header would slide up and down with the page.

The old page leaves first. It lifts 3vh and fades out in 300 ms. The new page starts 220 ms in and rises from 6vh below. The transition layer has a dark background, so the stage between the two pages is clean.

Only transform and opacity. I tried blur, and it stuttered on full-page snapshots. Moving and fading a page-sized snapshot is cheap. Blurring one is not.

pointer-events: none on the transition layer means the animation never blocks a click.

Reduced motion#

The React documentation has a note titled "Always check prefers-reduced-motion", and says React does not disable animations for this case. This is my version:

@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(*),
  ::view-transition-new(*) {
    animation: vt-fade 180ms linear both !important;
  }
  ::view-transition-new(*) {
    animation-direction: reverse !important;
  }
}
@keyframes vt-fade {
  to {
    opacity: 0;
  }
}

The page cross-fades in 180 ms with no movement. React's example turns the animation off entirely, which is also fine. I kept a short fade so the page change still reads as a change.

Where it does nothing#

  • First load. There is no old page to animate from.
  • Browsers without the API. According to the web.dev roundup for October 2025, Firefox 144 added same-document support, which made the feature Baseline newly available. Chrome and Edge have had it since 111, and the Chrome documentation lists Safari 18. Older versions of those browsers just swap.
  • The back button. The React docs say popstate navigations skip animations, per the router guidance. Back and forward swap instantly in my site.
  • Nodes before the boundary. React says enter and exit only activate when the boundary comes before any DOM nodes. A <div> above it breaks the transition, so the wrapper in template.tsx sits above any element of mine.

Names must also be unique: only one element with a given name can be mounted at a time. My header name is safe because there is one header.

A second use: a theme switch#

The Lab example Lumora Sign-in uses the browser API directly for a circular reveal when you switch between light and dark. That is the other half of the feature: React manages route changes, and a direct startViewTransition call suits a one-off effect that React does not own.

Browsers I did not try#

I have not tested the transition on real iOS Safari or on Firefox, so those rows rest on the sources above and not on my own device. The 620 ms entrance is a taste choice, not a measured one. And a transition that plays on every navigation is a cost on slow phones: I have not profiled it on a low-end Android.