UICraft / Craft
CSSView transitions

How View transitions works

Make a cover grow into its story, then use the same browser API to change a whole page theme.

Demo

Slow travel, written down.

How it works

01 — Begin with two ordinary layouts

The demo is a tiny blog. The journal page lists posts as cards, each with a cover and a title. Clicking a card shows that post: the same cover, much larger, under the same title. React state holds which post is open, or null for the journal. Before adding animation, clicking should already show the right page.

01-layout.tsx
const [openId, setOpenId] = useState<string | null>(null);
const post = POSTS.find((item) => item.id === openId);
 
return post ? (
  <article>
    <button type="button" onClick={() => setOpenId(null)}>All posts</button>
    <h2>{post.title}</h2>
    <Cover post={post} />
  </article>
) : (
  <ul>
    {POSTS.map((item) => (
      <li key={item.id}>
        <button type="button" onClick={() => setOpenId(item.id)}>
          <Cover post={item} />
          <span>{item.title}</span>
        </button>
      </li>
    ))}
  </ul>
);

The browser now has two pages to compare. Without a transition, the small cover in the card vanishes and a big one appears in the post.

02 — Name the element that persists

view-transition-name gives an element an identity in both views. The browser takes a snapshot of the named element before and after the DOM update and matches those snapshots by name. Its position and size can then animate as one object.

The name must be unique among the elements on screen. The journal shows three covers, so they can't all be called vt-cover. Instead, only the post you're opening holds the names. activeId remembers it, and stays set after you go back, so the same card is named on the way home too.

02-identity.tsx
const [activeId, setActiveId] = useState(POSTS[0].id);
 
const named = (id: string, part: "cover" | "title") =>
  id === activeId ? { viewTransitionName: `vt-${part}` } : undefined;
 
<Cover post={item} style={named(item.id, "cover")} />
<span style={named(item.id, "title")}>{item.title}</span>

The title gets a name too, so it slides from the card into the post heading instead of fading.

03 — Put the DOM change inside a transition

document.startViewTransition(update) asks the browser to capture the old view, run update, capture the new view, and animate between them. update must actually change the DOM. The API returns a ViewTransition object with promises for advanced coordination; this small interaction does not need to wait on them.

03-browser-api.tsx
document.startViewTransition(() => {
  // Change the DOM here.
});

React usually batches state updates, so calling setOpenId alone inside update may let the callback finish before the new DOM is present. flushSync commits the change before the browser takes its second snapshot.

The clicked card also needs its names before the first snapshot, so the browser can find it in the old view. That's a second flushSync, outside the transition:

03-react-update.tsx
import { flushSync } from "react-dom";
 
// Name the clicked card first, so the browser's "before" snapshot can find it.
if (nextId) flushSync(() => setActiveId(nextId));
document.startViewTransition(() => {
  flushSync(update);
});

04 — Tune the motion and keep the action usable

The browser supplies a default transition. Target the named groups' pseudo-elements to set how the cover and title travel. The rest of the page crossfades while those two keep their identity.

04-duration.css
::view-transition-group(vt-cover),
::view-transition-group(vt-title) {
  animation-duration: 450ms;
  animation-timing-function: cubic-bezier(.2, 0, 0, 1);
}

Try 150ms, then 900ms. The first is hard to follow; the second makes the interface feel slow. Timing is useful when it helps someone understand where an object went.

The feature check and motion preference check both take the plain state-update path. Cards and the back link stay real buttons with a visible keyboard focus outline. The browser cleans up its temporary snapshot elements when the transition ends; there are no listeners or timers to remove.

04-fallback.tsx
if (
  !document.startViewTransition ||
  window.matchMedia("(prefers-reduced-motion: reduce)").matches
) {
  if (nextId) setActiveId(nextId);
  update();
  return;
}

05 — A second use: switch the page theme

A theme switch does not have one object moving between slots. Instead, the entire page changes colors. This site's theme button uses the same API to crossfade from the old page snapshot to the new one. Try it here: the whole site, the blog demo included, fades to the other theme.

The theme update changes the root dark class and color-scheme synchronously, so it needs no React flushSync. It also saves the choice to localStorage. The important transition path in this site's ThemeToggle component is:

theme-switch-core.tsx
const nextDark = !document.documentElement.classList.contains("dark");
 
if (
  window.matchMedia("(prefers-reduced-motion: reduce)").matches ||
  !document.startViewTransition
) {
  applyTheme(nextDark);
  return;
}
 
document.startViewTransition(() => applyTheme(nextDark));

Here root means the full document snapshot, and CSS controls its fade. The cover example instead gives one element a distinct name so the browser can track its size and position. The site's global CSS uses a short 200ms fade for the theme:

theme-fade.css
::view-transition-old(root) { animation: 200ms ease-out both theme-fade-out; }
::view-transition-new(root) { animation: 200ms ease-out both theme-fade-in; }
 
@keyframes theme-fade-out { to { opacity: 0; } }
@keyframes theme-fade-in { from { opacity: 0; } }

06 — Choose the right transition

  • One object changes size or position: give it a unique view-transition-name, as with the blog cover.
  • The whole page changes appearance: transition the root view, as with the theme switcher.
  • The URL changes in Next.js: use React's <ViewTransition> with Link navigation; the Next.js guide covers shared elements across routes.

The MDN View Transitions guide explains the snapshots and pseudo-elements in more depth.

Check: Why does the cover need a unique name, while the theme switcher can animate the root snapshot?