Michael Samuel Naeem

The View Transitions API for Smooth SPAs

By Michael Samuel Naeem · February 8, 2026 · 14 min read

Engineering
Share on LinkedIn Share on X Share on Reddit Share on HN Share on Bluesky

title: "The View Transitions API for Smooth SPAs" slug: "view-transitions-api" description: "The View Transitions API explained: animate DOM and page changes with startViewTransition, cross-document transitions, and shared-element morphs — without a heavy animation library." datePublished: "2026-02-08" dateModified: "2026-07-17" tags:

title: "view-transitions-api" slug: "view-transitions-api" description: "" datePublished: "2026-07-17" dateModified: "2026-07-17" tags:

title: "view-transitions-api" slug: "view-transitions-api" description: "" datePublished: "2026-07-17" dateModified: "2026-07-17" tags:

title: "view-transitions-api" slug: "view-transitions-api" description: "" datePublished: "2026-07-17" dateModified: "2026-07-17" tags:

title: "view-transitions-api" slug: "view-transitions-api" description: "" datePublished: "2026-07-17" dateModified: "2026-07-17" tags:

title: "view-transitions-api" slug: "view-transitions-api" description: "" datePublished: "2026-07-17" dateModified: "2026-07-17" tags:

title: "The View Transitions API for Smooth SPAs" slug: "view-transitions-api" description: "The View Transitions API explained: animate DOM and page changes with startViewTransition, cross-document transitions, and shared-element morphs — without a heavy animation library." datePublished: "2026-02-08" dateModified: "2026-07-17" tags:

For years, animating a page transition on the web meant one of two bad options: hand-roll a fragile system that clones nodes, measures positions, and juggles CSS, or pull in a heavyweight animation library and accept the bundle cost. The View Transitions API replaces both. You call document.startViewTransition(), update the DOM inside the callback, and the browser handles snapshotting the before and after states and animating between them. The result is the kind of smooth, native-feeling transition — cross-fades, shared-element morphs, slide-ins — that used to be the exclusive domain of native apps.

I've shipped enough janky manual page transitions to genuinely enjoy this API. It moves the hard parts — measuring layout, coordinating two states, cleaning up — into the browser, and it fails safe: where it's unsupported, you just get an instant update.

The one function that does the work

The API's surface is deceptively small. You give the browser a callback that mutates the DOM; it does the rest:

function updateView(newContent) {
  if (!document.startViewTransition) {
    applyDomUpdate(newContent); // graceful fallback: no animation
    return;
  }
  document.startViewTransition(() => {
    applyDomUpdate(newContent); // your normal DOM update
  });
}

Under the hood the browser does four things: captures a snapshot of the current page, runs your callback to update the DOM, captures the new state, then animates from old to new. By default that animation is a smooth cross-fade of the whole page. The feature-detection guard (if (!document.startViewTransition)) is what makes this safe to ship today — unsupported browsers take the branch that just updates instantly.

Customizing with CSS pseudo-elements

The animation is driven entirely by CSS, through a tree of pseudo-elements the browser generates during the transition. The root cross-fade lives on ::view-transition-old(root) and ::view-transition-new(root), and you style them like any animation:

::view-transition-old(root) {
  animation: 200ms ease-out both fade-out;
}
::view-transition-new(root) {
  animation: 300ms ease-in both slide-from-right;
}

@keyframes slide-from-right {
  from { transform: translateX(30px); opacity: 0; }
  to   { transform: translateX(0);    opacity: 1; }
}

This is the part I appreciate as an engineer: the behavior is one JavaScript call, and the look is plain CSS you can tweak, theme, and reason about with normal tooling. There's no imperative animation timeline to babysit.

Shared-element transitions, the real magic

Cross-fades are nice; shared-element morphs are what make people say "wait, that's the web?" You tag an element with a view-transition-name, and if an element with the same name exists in both the old and new states, the browser animates it from its old geometry to its new geometry.

.thumbnail {
  view-transition-name: hero-image;
}
/* On the detail page, the large image also uses: */
.hero {
  view-transition-name: hero-image;
}

Click a thumbnail in a grid, navigate to the detail view, and the image visibly grows and slides into its new position while the rest of the page cross-fades around it. You wrote zero animation code for that. The one rule to internalize: a given view-transition-name must be unique on the page at any moment — two elements sharing the same name simultaneously breaks the transition. For lists, that usually means setting the name dynamically on just the item being interacted with.

Same-document versus cross-document

There are two flavors, and the distinction matters for architecture.

Type Trigger Best for
Same-document startViewTransition() after a client-side route change SPAs and framework routers
Cross-document Automatic, opt-in via CSS @view-transition Traditional multi-page sites

Same-document is the SPA case: your router updates the DOM inside the transition callback. Cross-document is the newer, quietly revolutionary one — you opt in with a single CSS rule and get animated transitions between actual separate HTML pages, no SPA required:

@view-transition {
  navigation: auto;
}

That means a plain server-rendered site, or an islands-architecture setup with Astro, can have polished page transitions without adopting a client-side router at all. For me that's the headline: the API erases one of the last real UX advantages SPAs held over multi-page sites.

Framework and PWA integration

Most routers now expose hooks for this. Astro ships a <ClientRouter /> that wraps navigations in view transitions; React and Vue router integrations wrap route changes in startViewTransition. The pattern is always the same — the framework calls the API around its DOM update, and you supply the CSS. When you're building an installable, app-like experience, view transitions are one of the cheapest ways to close the perceived-quality gap with native, which is why I treat them as standard kit alongside the rest of a progressive web app in 2026.

The honest caveats

It's a great API, but I've hit its edges:

@media (prefers-reduced-motion: reduce) {
  ::view-transition-group(*),
  ::view-transition-old(*),
  ::view-transition-new(*) {
    animation: none !important;
  }
}

Worth adopting now

Because the API degrades to a plain DOM update when unsupported, there's essentially no downside to layering it on as progressive enhancement — you add delight where it works and lose nothing where it doesn't. Start with a global cross-fade for route changes, add one or two shared-element morphs on your highest-traffic flow (grid-to-detail is the classic), and keep durations tight with reduced-motion handled. That's a couple of hours of work for a genuinely native-feeling result, without a single animation library in your bundle. After years of gluing this together by hand, having it be a browser primitive still feels like a small gift.

MPA navigation requirement

Cross-document transition requires @view-transition { navigation: auto } on both pages — missing on destination broke animation silently in Safari Technology Preview. Wrap in prefers-reduced-motion: no-preference; cross-fade only for reduced motion users.

MPA navigation requirement

Cross-document transition requires @view-transition { navigation: auto } on both pages — missing on destination broke animation silently in Safari Technology Preview. Wrap in prefers-reduced-motion: no-preference; cross-fade only for reduced motion users.

Framework integration details

Vue Router:

router.beforeResolve(async (to, from) => {
  if (!document.startViewTransition) return true;
  return new Promise((resolve) => {
    document.startViewTransition(async () => {
      resolve(true);
      await router.isReady();
    });
  });
});

Next.js App Router — View Transitions API integration is evolving; use document.startViewTransition wrapping router.push in client components for soft navigations within same layout. Cross-layout transitions may need @view-transition meta for MPA-style navigations.

Astro — mostly MPA; cross-document view transitions apply when enabling @view-transition { navigation: auto; } in shared layout CSS.

Performance measurement

View transitions add snapshot and animation cost. Profile on low-end devices—animating large DOM snapshots can frame-drop. Scope transitions to layout shell; avoid transitioning data-heavy tables. Use Chrome Performance panel → Frames during transition; target 60fps or reduce duration under prefers-reduced-motion.

If INP regresses after adding transitions, default to instant navigation on interactive dashboards; keep transitions on marketing pages only.

Resources

Architecture decisions around view transitions api

Operating view transitions api well means tying design choices to measurable outcomes and explicit owners. Ambiguous ownership is how pages rot.

For view transitions api:

Revisit the design when the metric that justified view transitions api stops moving — sunsetting is a feature.

Signal Target Alarm
Plan apply time Team-defined SLO Page on burn rate
Drift open count Baseline − noise Ticket if sustained
Failed policy checks Budget cap Weekly review

Ownership and on-call for view transitions api

Reviewers should challenge assumptions encoded in view transitions api: defaults copied from tutorials, timeouts that exceed upstream SLAs, and authz checks applied only on the primary UI path. Require a short threat or failure note in the PR when the change touches a trust boundary.

Concrete probes:

  1. Scenario C for view transitions api: traffic 3× baseline — prove autoscaling or shedding keeps the golden journey healthy.
  2. Scenario A for view transitions api: partial dependency outage — prove clients degrade gracefully and retries do not amplify load.
  3. Scenario B for view transitions api: bad config shipped — prove rollback within the declared RTO without data corruption.

Cross-team contracts for view transitions api

Roll out view transitions api behind a flag or weighted route when possible. Start with internal users or a low-risk geography. Watch the signals in the table for at least one full business cycle before calling the migration done. Keep the previous path warm until error budgets stabilize.

Document the owner, the dashboard, and the single command that reverts the change. If that sentence is hard to write, the design is not ready for production traffic.

Observability cardinality around view transitions api

Detail 1 (333): for view transitions api, define the contract between producers and consumers explicitly — payload shape, timeout, and idempotency key. When observability cardinality around view transitions api becomes painful, it is usually because that contract was implicit.

I keep a short matrix: who can break view transitions api, how we detect it within five minutes, and who is paged. Update the matrix when ownership moves. Add one synthetic check that exercises the failure path, not only the happy path. Prefer checks that run continuously over quarterly manual reviews that everyone skips under deadline pressure.

If you only remember one thing about view transitions api: optimize for reversible decisions. Reversibility beats cleverness when the incident channel is busy and the blast radius is unclear.

Caching interactions with view transitions api

Detail 2 (907): for view transitions api, define the contract between producers and consumers explicitly — payload shape, timeout, and idempotency key. When caching interactions with view transitions api becomes painful, it is usually because that contract was implicit.

I keep a short matrix: who can break view transitions api, how we detect it within five minutes, and who is paged. Update the matrix when ownership moves. Add one synthetic check that exercises the failure path, not only the happy path. Prefer checks that run continuously over quarterly manual reviews that everyone skips under deadline pressure.

If you only remember one thing about view transitions api: optimize for reversible decisions. Reversibility beats cleverness when the incident channel is busy and the blast radius is unclear.

Frequently asked questions

What is the main production risk with view transitions api?

Teams ship without field measurement—view transitions api failures appear as silent UX regressions, cost drift, or audit findings rather than clear errors.

When should we prioritize view transitions api?

Prioritize when user research, CrUX, support tickets, or compliance requirements show pain on critical paths—not when a checklist mentions it abstractly.

How do we validate view transitions api changes?

Baseline RUM before changes, compare p75 after deploy, and keep rollback via feature flags or cache purge documented in the PR.

Hiring a senior Android / Flutter engineer?

I architect and ship production mobile software — Kotlin, Jetpack Compose, Flutter — for robotics, EV infrastructure, fintech, and real-time systems. Open to remote roles in Europe and the US.

Get in touch →