Page Transitions in Next.js 16 with the View Transitions API
Crossfade, slide and morph between pages with document.startViewTransition, then wire the same idea into the App Router with React's ViewTransition component.
Page transitions used to mean keeping both pages mounted at once, measuring where everything was and animating the difference yourself. The View Transitions API turns that inside out. The browser takes a picture of the page, lets you change the DOM however you like, captures the new state, and animates between the two.
The final result
Open a project, then go back. The thumbnail and the title are not two elements fading in and out, the browser treats each as one element that moves and resizes from the list into the detail page. Switch the animation to slide or crossfade to see what each layer adds.
What we are building
document.startViewTransition(update) captures the current state of every element that has a view-transition-name, runs your update callback, captures the new state and builds a tree of pseudo-elements on top of the page. For each name you get a ::view-transition-group that animates position and size from old to new, and inside it ::view-transition-old and ::view-transition-new, two snapshots that crossfade. When an element with the same name exists before and after, that group is what makes it look like one element travelling.
Everything you style is a pseudo-element hanging off <html>, so the animations are plain CSS keyframes. There is no layout measuring in your code and no second copy of the page.
Setting up
There are two routes in Next.js 16, and they meet in the same browser API.
The React route is the <ViewTransition> component, which React exports from its stable build since 19.3. The App Router needs no configuration for it anymore. Up to Next.js 16.2 there was an experimental.viewTransition flag in next.config, and 16.3 removed it, so if an older tutorial tells you to add it, leave it out.
import { ViewTransition } from 'react';The direct route needs nothing at all, which is what the demo on this page uses. Same-document transitions have shipped in every major engine, in Chrome and Edge since version 111, Safari since 18 and Firefox since 144. Pick one route per app. React calls startViewTransition itself for <ViewTransition>, and the React docs say not to call it yourself next to that.
Step 1: Wrap the state change
The whole integration is one call around your state update, plus a check for browsers that lack the API.
import { flushSync } from 'react-dom';
if (!document.startViewTransition) {
setView(next);
} else {
document.startViewTransition(() => {
flushSync(() => setView(next));
});
}The if is the fallback. Where the API is missing, the page still changes, just without animation.
flushSync is the part people miss. The browser expects the DOM to be in its new state once the callback is done, but React schedules a state update instead of applying it on the spot. flushSync makes React write the change to the DOM inside the callback, before the browser looks. Then give the page container a name so it gets its own group.
.page { view-transition-name: page; }That is the default animation, a crossfade, and it already hides the hard cut between two pages.
Step 2: Give it a direction
A crossfade does not know whether you went forward or back. Set an attribute on <html> before you start the transition and select on it, since that is where the pseudo-elements live.
:root[data-direction='forward']::view-transition-old(page) {
animation-name: slide-out-left;
}
:root[data-direction='forward']::view-transition-new(page) {
animation-name: slide-in-right;
}Newer engines can do this without the attribute. Pass types: ['forward'] to startViewTransition and select with :active-view-transition-type(forward). That arrived later than the API itself, in Chrome and Edge from version 125, Safari from 18.2 and Firefox from 147, which is why the demo keeps the attribute.
Step 3: Morph the shared element
Give the thumbnail on the list and the hero on the detail page the same view-transition-name, and the browser pairs them. A name must be unique in the document while the transition runs, otherwise the browser skips the whole transition. With a list of cards, put the name on the clicked card just before you start, and nowhere else. Name every card and each one becomes its own group, fading out in place while the page around it slides.
In the App Router you write the same thing with React. Every <Link> navigation already runs inside a transition, so <ViewTransition> animates on its own.
import Image from 'next/image';
import { ViewTransition } from 'react';
<ViewTransition name={`thumb-${project.id}`}>
<Image src={project.cover} alt='' width={640} height={400} />
</ViewTransition>Use that same name on the list card and on the detail page and React pairs the one that appears on both sides. The id in the name keeps every card unique. The morph only plays when the detail page renders in the same commit as the navigation, which is the case for prefetched pages. <Link transitionTypes={['forward']}>, added in Next.js 16.2, passes the direction through. @types/react only declares ViewTransition in its main types from 19.3. Older versions keep it in the react/canary types, so update them if TypeScript cannot find the export.
Where this runs out
Snapshots are pictures. The old one is a still image and the new one stays live, but neither gets laid out again while it moves. A thumbnail growing into a hero is a picture being stretched, so text inside a morphing group scales instead of reflowing, which is why the demo names the title separately from the card.
A transition started with document.startViewTransition belongs to the whole document. Two of them cannot run at once, starting a second one skips the first, and by default the entire page is captured as a single root group. The demo sets view-transition-name: none on the root while it runs, so the rest of this article stays live. Chrome and Edge 147 added element.startViewTransition, which scopes a transition to one part of the page, but Safari and Firefox do not have it yet.
Full page loads are a separate feature. The @view-transition at-rule opts two same-origin pages into a transition when you navigate from one to the other, but Firefox only has it in Nightly so far. Chrome and Edge have had it since 126 and Safari since 18.2. Next.js client navigations never need it, because they stay inside one document.
From here, look at view-transition-class, which styles many groups with one selector instead of one rule per name.