SuperAPI AI Directory

view-transitions

General & other

View repository

Updated 10-16 06:14

About this skill

View Transitions API

Guide to implementing view transitions in SPAs and MPAs, with support for React and Next.js.

Mental Model

The View Transitions API automates the FLIP pattern (First, Last, Invert, Play) at the browser level. The browser captures screenshots of the current state, you update the DOM, the browser captures the new state and animates between both using CSS Animations on generated pseudo-elements.

There are two variants that share the same building blocks:

Variant Trigger Use case
Same-document (SPA) document.startViewTransition(callback) State changes in SPAs
Cross-document (MPA) Navigation + @view-transition CSS at-rule Navigation between HTML pages

Browser Support

  • Same-document: Chrome 111+, Edge 111+, Safari 18+, Firefox 133+ — Baseline Newly Available
  • Cross-document: Chrome 126+, Edge 126+, Safari 18.2+ — Firefox: in development
  • view-transition-class: Chrome 125+, Safari 18.2+, Firefox 144+
  • match-element: Chrome 137+, Safari 18.2+, Firefox 144+

Cross-document transitions is a focus of Interop 2026. Always implement with graceful fallback. Check current support on caniuse.com.

Quick Implementation

Same-Document (SPA)

function navigateWithTransition(updateFn: () => void) {
  // SIEMPRE feature detection
  if (!document.startViewTransition) {
    updateFn();
    return;
  }
  document.startViewTransition(() => updateFn());
}

Cross-Document (MPA)

Add in the global CSS (both pages, origin and destination):

/* Opt-in — reemplaza el meta tag obsoleto */
@view-transition {
  navigation: auto;
}

Name Elements for Transition

/* Mismo view-transition-name en ambos estados = shared element transition */
.thumbnail { view-transition-name: product-hero; }
.hero-image { view-transition-name: product-hero; }

Critical Rules

Always follow these rules when implementing view transitions:

  1. Mandatory feature detection — Always check document.startViewTransition before using it. Without this, browsers without support break.

  2. unique view-transition-name per snapshot — Two visible elements with the same name silently abort the transition. It is the most common bug #1.

  3. prefers-reduced-motion — Always respect. Add this CSS in every project:

    @media (prefers-reduced-motion: reduce) {
      ::view-transition-group(*),
      ::view-transition-old(*),
      ::view-transition-new(*) {
        animation: none !important;
      }
    }
    
  4. Duration < 500ms — Sweet spot: 200-400ms. Long transitions keep snapshots in GPU memory.

  5. Limit named elements — Each name creates an old+new pair of rasterized snapshots. 50 elements = 100 images in memory. Be selective.

  6. Lightweight callback — The browser waits for the callback of startViewTransition() to finish before capturing the new state. Do not put heavy computation there.

  7. animation-fill-mode: forwards — Apply to custom animations to avoid flicker at the end.

  8. Do not use the obsolete meta tag — <meta name="view-transition"> is obsolete. Use @view-transition { navigation: auto; }.

  9. MPA: opt-in on BOTH pages — The at-rule must be in the CSS of the origin page AND the destination page.

  10. React: do not use flushSync — A flushSync during a view transition forces React to apply updates synchronously, which skips the flow of startViewTransition.

Pseudo-elements

During the transition, the browser generates this tree that can be styled with CSS:

::view-transition
  ::view-transition-group(name)
    ::view-transition-image-pair(name)
      ::view-transition-old(name)      → screenshot estado anterior
      ::view-transition-new(name)      → vista live del nuevo estado

Customize:

/* Duracion global */
::view-transition-group(*) { animation-duration: 0.4s; }

/* Desactivar crossfade root, solo animar named elements */
::view-transition-group(root) { animation: none; }

ViewTransition Object (SPA)

startViewTransition() returns an object with three promises:

Promise Resolves when...
updateCallbackDone The DOM callback finished
ready The pseudo-elements are created, animation about to start
finished The animation finished, new view visible and interactive

Use transition.ready to hijack the default animation with the Web Animations API (e.g.: circular reveal).

View Transition Types (SPA)

To condition CSS animations based on the type of navigation:

document.startViewTransition({
  update: () => updateDOM(),
  types: ['slide-forward'],
});
:active-view-transition-type(slide-forward) {
  &::view-transition-old(root) { animation: slide-to-left 0.3s; }
  &::view-transition-new(root) { animation: slide-from-right 0.3s; }
}

New Features

match-element

Auto-naming for long lists without naming each element:

.card {
  view-transition-name: match-element;
  view-transition-class: card;
}

view-transition-class

Group multiple named elements under a single animation:

::view-transition-group(*.card) {
  animation-duration: 0.3s;
}

Scoped View Transitions (experimental)

element.startViewTransition() instead of document.startViewTransition(). Allows multiple simultaneous transitions in different subtrees. Not production-ready yet.

Integration with React and Next.js

For detailed integration patterns, read references/react-nextjs.md.

Quick summary:

  • React canary has <ViewTransition> native component
  • Next.js has experimental flag viewTransition: true in next.config.js
  • next-view-transitions (Shu Ding) is the pragmatic solution for App Router
  • For imperative control, use a wrapper hook over startViewTransition()

Animation Patterns

For common patterns (slide direction, product gallery morph, modal transitions), read references/animation-patterns.md.

Debugging

  • Chrome DevTools > Animations panel to scrub transitions
  • Slow down to 10% to inspect
  • Pseudo-elements visible in the Elements panel during the transition

Common problems:

  • Transition does not animate → Check for visible duplicate names
  • Transition is aborted → The callback threw an error
  • Broken overflow → Content in transition breaks containment, use CSS containment strategies
  • React skips transition → There is a flushSync in the middle

Pre-Deploy Checklist

[ ] Feature detection con fallback
[ ] prefers-reduced-motion implementado
[ ] Duracion < 500ms
[ ] view-transition-names unicos por estado
[ ] Elementos nombrados limitados (no 50+)
[ ] Callback liviano
[ ] animation-fill-mode: forwards en custom animations
[ ] MPA: @view-transition en AMBAS paginas + same-origin
[ ] Testeado en Chrome, Safari Y Firefox
[ ] No meta tag obsoleto
[ ] React: sin flushSync en transitions