CSS View Transitions API: Progressive Enhancement for Page and State Animations

Badar KhalilUpdated September 30, 2026 5 min read

What are view transitions?

The View Transitions API lets the browser animate between two states of a page. It takes a snapshot of the old view, applies your DOM or page change, takes a snapshot of the new view and then cross-fades or animates between them. It works for same-document changes (for example, switching a theme, reordering a list or opening a detail view in a single-page app) and, in supporting browsers, for cross-document navigation between normal multi-page website pages.

Focus keyword: View Transitions API. Related trending keywords: document.startViewTransition, view-transition-name, @view-transition navigation auto, ::view-transition-old and ::view-transition-new, shared element transition, page transition CSS, MPA view transitions, view-transition-class.

Why treat it as progressive enhancement?

Browser support differs between same-document and cross-document transitions, and between browsers and versions. The safe approach is: your site must work exactly the same without the animation. If the browser does not support it, the content simply updates instantly. Always feature-detect in JavaScript, use @supports or the at-rule where appropriate, and verify support on Can I use before you depend on the feature.

Same-document transitions (SPA or JS state changes)

Wrap your DOM update in document.startViewTransition(callback). The browser captures the old state, runs the callback to update the DOM, captures the new state, and animates between them. A safe wrapper looks like this:

If document.startViewTransition does not exist, run the update directly.
Otherwise call document.startViewTransition(() => update()).

The returned object has promises: ready (pseudo-elements are created, animation is about to start), finished (animation complete) and updateCallbackDone. It also has skipTransition().

The pseudo-element tree

::view-transition: root overlay.
::view-transition-group(name): handles position and size movement.
::view-transition-image-pair(name): holds old and new snapshots.
::view-transition-old(name): snapshot before the change.
::view-transition-new(name): snapshot after the change.

The default for the whole page is the name root, a simple cross-fade. You can restyle it with normal CSS animations, for example: ::view-transition-old(root) { animation: fade-out .3s; }.

view-transition-name: shared element transitions

Give an element a unique view-transition-name in both states (like hero-image). The browser will morph its size and position between the old and new versions, which creates the popular shared element or hero transition. Rules: names must be unique on the page at the moment of capture, and duplicates cause the transition to be skipped. For lists, set a name per item using inline styles or attr() alternatives, or use view-transition-class to apply shared styling to many named elements.

Cross-document (multi-page) transitions

For normal navigations between same-origin pages, opt in with CSS on both pages: @view-transition { navigation: auto; }. Then use view-transition-name on elements that exist on both pages to morph them. Events such as pageswap and pagereveal let you customize the transition with JavaScript. Keep pages fast: the transition waits for the new page to be ready to render, so slow pages will feel slow.

View transition types

You can pass types (for example forward and back) and target them with :active-view-transition-type(forward) in CSS to use different animations per direction.

Accessibility and performance

Respect prefers-reduced-motion: disable or shorten custom animations, or keep only a simple fade.
Keep durations short (about 200ms to 400ms).
During a transition, the page shows snapshots, so the old content is not interactive. Keep it brief.
Focus management still matters. After the update, move focus to a sensible place and update the page title for SPAs.
Do not rely on it to communicate state. Use normal, accessible DOM changes.

Quick summary

Use the View Transitions API to add polished state and page animations with very little code. Feature-detect, keep the no-animation path fully functional and respect reduced motion.

Try it Yourself HTML

<style>
  :root { --bg: #ffffff; --fg: #0f172a; }
  :root.dark { --bg: #0f172a; --fg: #f8fafc; }
  body { margin: 0; min-height: 200px; display: grid; place-items: center; background: var(--bg); color: var(--fg); font-family: system-ui, sans-serif; }
  button { padding: 12px 20px; border-radius: 10px; border: 0; background: #6366f1; color: #fff; font-weight: 600; cursor: pointer; }
  ::view-transition-old(root), ::view-transition-new(root) { animation-duration: .45s; }
</style>
<div><h2>Theme toggle</h2><button id='toggle'>Toggle theme</button></div>
<script>
  function update() { document.documentElement.classList.toggle('dark'); }
  document.getElementById('toggle').addEventListener('click', function () {
    if (!document.startViewTransition) { update(); return; }
    document.startViewTransition(function () { update(); });
  });
</script>

Output

Press Run to execute.

Try it Yourself HTML

<style>
  body { font-family: system-ui, sans-serif; padding: 24px; }
  .grid { display: flex; gap: 12px; flex-wrap: wrap; }
  .tile { width: 90px; height: 90px; border-radius: 12px; color: #fff; display: grid; place-items: center; font-weight: 700; cursor: pointer; }
  .a { background: #ef4444; view-transition-name: tile-a; }
  .b { background: #10b981; view-transition-name: tile-b; }
  .c { background: #3b82f6; view-transition-name: tile-c; }
  .d { background: #f59e0b; view-transition-name: tile-d; }
</style>
<button id='shuffle'>Shuffle tiles</button>
<div class='grid' id='grid' style='margin-top: 16px'>
  <div class='tile a'>A</div><div class='tile b'>B</div><div class='tile c'>C</div><div class='tile d'>D</div>
</div>
<script>
  function shuffle() {
    var grid = document.getElementById('grid');
    var items = Array.prototype.slice.call(grid.children);
    items.sort(function () { return Math.random() - 0.5; });
    items.forEach(function (el) { grid.appendChild(el); });
  }
  document.getElementById('shuffle').addEventListener('click', function () {
    if (!document.startViewTransition) { shuffle(); return; }
    document.startViewTransition(shuffle);
  });
</script>

Output

Press Run to execute.

Try it Yourself HTML

<style>
  body { font-family: system-ui, sans-serif; padding: 24px; }
  .thumb { width: 120px; height: 80px; border-radius: 10px; background: linear-gradient(135deg, #8b5cf6, #ec4899); cursor: pointer; }
  .full { width: 100%; max-width: 420px; height: 240px; border-radius: 16px; background: linear-gradient(135deg, #8b5cf6, #ec4899); }
  .hero { view-transition-name: hero; }
  .hidden { display: none; }
  ::view-transition-group(hero) { animation-duration: .5s; animation-timing-function: cubic-bezier(.2, .8, .2, 1); }
</style>
<div id='list'><div class='thumb hero' id='thumb'></div><p>Click the thumbnail to morph it into a large image.</p></div>
<div id='detail' class='hidden'><div class='full' id='full'></div><p><button id='back'>Back</button></p></div>
<script>
  function show(detail) {
    var t = document.getElementById('thumb');
    var f = document.getElementById('full');
    document.getElementById('list').classList.toggle('hidden', detail);
    document.getElementById('detail').classList.toggle('hidden', !detail);
    if (detail) { t.classList.remove('hero'); f.classList.add('hero'); } else { f.classList.remove('hero'); t.classList.add('hero'); }
  }
  function go(detail) {
    if (!document.startViewTransition) { show(detail); return; }
    document.startViewTransition(function () { show(detail); });
  }
  document.getElementById('thumb').addEventListener('click', function () { go(true); });
  document.getElementById('back').addEventListener('click', function () { go(false); });
</script>

Output

Press Run to execute.

Try it Yourself CSS

/* shared.css: include on every page of a same-origin multi-page site */
@view-transition {
  navigation: auto;
}

/* Morph the site header between pages */
header.site {
  view-transition-name: site-header;
}

/* Custom page animation */
@keyframes fade-out { to { opacity: 0; transform: translateY(-10px); } }
@keyframes fade-in { from { opacity: 0; transform: translateY(10px); } }

::view-transition-old(root) {
  animation: .25s ease-in both fade-out;
}
::view-transition-new(root) {
  animation: .35s ease-out both fade-in;
}

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

Output

Press Run to execute.

Exercise: Add a safe view transition to a list reorderHTML

Wrap the DOM update in document.startViewTransition, but only when the API exists and the user does not prefer reduced motion. Give every list item a unique view-transition-name so items slide to their new positions.

Try it Yourself HTML

<style>
  li { padding: 10px; margin: 6px 0; background: #e0e7ff; border-radius: 8px; list-style: none; width: 220px; font-family: system-ui, sans-serif; }
  /* TODO: unique view-transition-name for each li */
</style>
<button id='rev'>Reverse</button>
<ul id='list'><li id='one'>One</li><li id='two'>Two</li><li id='three'>Three</li></ul>
<script>
  function reverse() {
    var ul = document.getElementById('list');
    Array.prototype.slice.call(ul.children).reverse().forEach(function (li) { ul.appendChild(li); });
  }
  document.getElementById('rev').addEventListener('click', function () {
    // TODO: feature-detect startViewTransition and prefers-reduced-motion
    reverse();
  });
</script>

Output

Press Run to execute.

Show expected output

Clicking Reverse smoothly slides the list items into their new order in supporting browsers, and instantly reorders them in browsers without support or when reduced motion is on.

This is a self-check — compare your result with the expected output above.

Was this page helpful?