Color scheme

View Transitions API

When a user clicks a card and the page swaps to a detail view, the default experience is an instant jump. The old content disappears and the new content appears in a single frame. The View Transitions API gives the browser a way to animate that swap smoothly, capturing a snapshot of what the page looks like before the change and crossfading or morphing it into what it looks like after. The result feels closer to a native app than a web page, and the minimum code required to enable it is remarkably small.

Same-Document vs. Cross-Document

The View Transitions API covers two scenarios that work differently and have different browser support. Same-document transitions animate DOM changes within a single page and are supported in Chrome 111+, Edge 111+, Safari 18+, and Firefox 144+, covering roughly 89% of users. Cross-document transitions animate navigations between separate HTML files and are currently supported only in Chrome 126+ and Edge 126+. This page focuses on same-document transitions. Cross-document support is noted where relevant.

How the API Works

The core mechanism is a snapshot-and-animate model. When you call document.startViewTransition() and pass it a callback that updates the DOM, the browser does the following:

  • Captures a screenshot of the current page state before the callback runs.
  • Runs your callback, applying your DOM changes.
  • Captures a screenshot of the new page state after the callback.
  • Animates between the two screenshots using a set of generated pseudo-elements, then removes them once the animation finishes.

The generated pseudo-elements form a tree rooted at ::view-transition, which sits above all page content in the stacking order during the animation. By default, the entire page crossfades as a single unit. You can opt individual elements into their own named transitions using view-transition-name, which gives each named element its own group in the pseudo-element tree and enables the morph effect.


    /* ::view-transition pseudo-element tree */
    ::view-transition
    └── ::view-transition-group(root)          /* one per named element + root */
        └── ::view-transition-image-pair(root)
            β”œβ”€β”€ ::view-transition-old(root)    /* snapshot of old state */
            └── ::view-transition-new(root)    /* snapshot of new state */

The Minimal Pattern

The simplest possible view transition wraps any DOM update in document.startViewTransition(). The callback can be synchronous or return a promise. If it returns a promise, the browser waits for it to resolve before capturing the new state snapshot, which is useful for fetch-based content updates.


    // Without view transitions: instant swap
    function showDetail(id) {
        document.querySelector('.list-view').hidden = true;
        document.querySelector('.detail-view').hidden = false;
    }

    // With view transitions: animated crossfade
    function showDetail(id) {
        document.startViewTransition(() => {
            document.querySelector('.list-view').hidden = true;
            document.querySelector('.detail-view').hidden = false;
        });
    }

That single wrapper is enough to get a smooth crossfade between the two states with no CSS changes. The browser supplies a default 300ms crossfade animation on ::view-transition-old(root) and ::view-transition-new(root).

Feature Detection Is Required

Always check for document.startViewTransition before calling it. In browsers that do not support the API, fall back to the unwrapped DOM update so the page still works.


    function showDetail(id) {
        const update = () => {
            document.querySelector('.list-view').hidden = true;
            document.querySelector('.detail-view').hidden = false;
        };

        if (document.startViewTransition) {
            document.startViewTransition(update);
        } else {
            update();
        }
    }

Named Elements and the Morph Effect

The real power of the API comes from giving specific elements a view-transition-name. When an element has a name before the transition and an element with the same name exists after the transition, the browser treats them as the same logical element and animates between the two positions and sizes. This produces the morph effect: a card shrinks or expands into a detail panel, a thumbnail grows into a hero image, or a list item slides and reshapes into a full view.


    /* Name the card in the list view */
    .card.is-selected {
        view-transition-name: active-card;
    }

    /* Name the matching container in the detail view */
    .detail-header {
        view-transition-name: active-card;
    }

Two rules apply to view-transition-name values that are easy to violate accidentally. First, every name must be unique on the page at any given moment. Two elements with the same name at the same time causes the transition to skip for both of them. Second, named elements are automatically given isolation: isolate and lifted out of their normal stacking context during the transition, which can affect how they composite with surrounding content.


    function showDetail(cardEl) {
        // Apply the name just before the transition starts
        cardEl.style.viewTransitionName = 'active-card';

        document.startViewTransition(() => {
            // Swap the views
            cardEl.closest('.list-view').hidden = true;
            document.querySelector('.detail-view').hidden = false;

            // Clear the name after DOM update so it doesn't persist
            cardEl.style.viewTransitionName = '';
        });
    }
Assigning Names Dynamically

Assigning view-transition-name in JavaScript just before calling startViewTransition() is a common pattern. It avoids having a name permanently on an element (which could conflict if multiple elements exist) and keeps the CSS clean. Clear the name inside the callback after your DOM update so the name does not persist into the new state where it might collide with something else.

Customizing the Animation

The default crossfade is a good starting point, but you can override it with any CSS animation by targeting the pseudo-elements directly. Each named group gets its own ::view-transition-old(name) and ::view-transition-new(name) pair that you can style independently.


    /* Override the default crossfade for the root */
    ::view-transition-old(root) {
        animation: 200ms ease-in both fade-out;
    }

    ::view-transition-new(root) {
        animation: 300ms ease-out both fade-in;
    }

    /* Custom slide for a named element */
    ::view-transition-old(active-card) {
        animation: 300ms ease-in both slide-out-left;
    }

    ::view-transition-new(active-card) {
        animation: 300ms ease-out both slide-in-right;
    }

    @keyframes fade-out {
        to { opacity: 0; }
    }

    @keyframes fade-in {
        from { opacity: 0; }
    }

For the morph between two differently sized elements, the browser handles position and size interpolation automatically inside ::view-transition-group(name). You rarely need to style the group directly unless you want to change the easing of the geometric interpolation.

Seeing the Morph

The demo below shows a grid of project cards in one panel. Clicking a card morphs that card into a full detail view in the same space while the rest of the grid crossfades away. The morph is driven by document.startViewTransition() with a dynamically assigned view-transition-name. Use the Slow Motion toggle when you want to stretch the animation even further for study or recording.

In browsers that do not support the API, clicking a card still works but the swap is instant. The note at the top of the demo tells you which experience you are seeing.

Click a card to morph it into the detail view.

CSS

Design Tokens

Color, spacing, and type organized into a token-first architecture.

Click to View Details

Layout

Grid Systems

Named areas, auto-fit tracks, and subgrid alignment patterns.

Click to View Details

Motion

Transitions

Easing curves, timing functions, and reduced-motion support.

Click to View Details

Cross-Document Transitions

Same-document transitions require JavaScript to call document.startViewTransition(). Cross-document transitions work across full page navigations between separate HTML files with no JavaScript required. You opt both the outgoing and incoming documents in using the @view-transition at-rule:


    /* Add to both pages that should animate between each other */
    @view-transition {
        navigation: auto;
    }

With both pages opted in, navigating between them produces a crossfade by default. Named elements work exactly as they do in same-document transitions: give an element on the list page and a matching element on the detail page the same view-transition-name and the browser morphs between them across the navigation.

Cross-Document Support: Chrome 126+ and Edge 126+ Only

Cross-document view transitions are not yet supported in Firefox or Safari. If you use @view-transition { navigation: auto; }, unsupported browsers simply navigate normally with no animation. The opt-in model means no JavaScript fallback is needed, but test in Firefox and Safari to confirm your pages are still fully functional without the effect.

Honest Limitations

The View Transitions API is well-designed, but a few constraints are worth knowing before you rely on it heavily.

  • Names must be unique. Two elements with the same view-transition-name on the page at the same time causes both to be excluded from the named transition. This is easy to hit in list views where you might want to name every card. Assign names dynamically just before the transition and clear them inside the callback.
  • Transitions cannot be nested. Calling document.startViewTransition() while a transition is already running skips the previous one. If your UI allows rapid interactions, debounce or queue them.
  • iframes are excluded. Content inside iframes does not participate in view transitions on the parent document. Cross-origin iframes are never included; same-origin iframes may be in the future but are not today.
  • Named elements get their own stacking context. view-transition-name creates a new stacking context on the element, similar to isolation: isolate. This can clip or reorder content that previously relied on the default stacking order.
  • The API is JavaScript-first for same-document transitions. There is no pure CSS way to trigger a same-document view transition. If JavaScript is unavailable, the swap happens without animation.
  • Cross-document: Firefox and Safari not yet. The @view-transition at-rule for multi-page navigation is Chrome and Edge only at the time of writing.

Reduced Motion

View transitions are animations. Apply prefers-reduced-motion guards by targeting the pseudo-elements directly. Setting animation-duration to a near-zero value effectively disables the visual transition while still allowing the DOM update to complete correctly.


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

Setting duration to zero exactly can cause edge cases in some browsers where the transition callback does not resolve cleanly. Using 0.01ms keeps the transition technically active but imperceptibly fast, which avoids those edge cases while still respecting the user preference.

Build Your Demo

You have two options for where to build your portfolio demo:

  • Combine: Extend your motion prove assignment at unit-6/motion/index.html. Add document.startViewTransition() to an existing interaction on the page and use view-transition-name to produce a morph on at least one named element.
  • Standalone: Create a new directory at unit-6/view-transitions/ with index.html and view-transitions.css. Build a list-to-detail interaction from scratch.

Whichever path you choose, your demo must include:

  • A same-document view transition triggered by document.startViewTransition() with proper feature detection and a working fallback.
  • At least one named element using view-transition-name that produces a visible morph between the before and after states.
  • A prefers-reduced-motion block that disables or drastically shortens the transition for users who prefer reduced motion.
  • If you choose the standalone path, add a link to your demo on your portfolio homepage and in your README.md.

Teaching Video Checklist

When you record your teaching video, make sure your teammates come away understanding these concepts:

  • What the snapshot-and-animate model is and why it means you only need to change the DOM normally inside the callback, with no manual clone or positioning code.
  • The difference between the default full-page crossfade and what happens when you add view-transition-name to an element, demonstrated on your actual demo. Optional: use the Slow Motion toggle while recording so teammates can study the snapshots frame by frame.
  • Why view-transition-name values must be unique on the page at any given moment and how to handle that constraint when working with lists of items.
  • The same-document versus cross-document distinction, including the current browser support gap for cross-document transitions.
  • Your portfolio demo: show the interaction without the view transition first, then show it with the transition enabled, so teammates see the before and after clearly.

Start by opening DevTools and slowing down animations to 25% speed so the morph is easy to see. Walk through the snapshot model visually before showing any code, then show the minimal wrapper, then layer in the named element.

Resources