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.
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).
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 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.
Design Tokens
Color, spacing, and type organized into a token-first architecture.
Click to View Details
Grid Systems
Named areas, auto-fit tracks, and subgrid alignment patterns.
Click to View Details
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 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-nameon 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-namecreates a new stacking context on the element, similar toisolation: 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-transitionat-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. Adddocument.startViewTransition()to an existing interaction on the page and useview-transition-nameto produce a morph on at least one named element. -
Standalone: Create a new directory at
unit-6/view-transitions/withindex.htmlandview-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-namethat produces a visible morph between the before and after states. -
A
prefers-reduced-motionblock 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-nameto 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-namevalues 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
-
MDN: View Transition API — Full API reference including
ViewTransitionobject, promise chain, and pseudo-element tree - MDN: view-transition-name — Property reference with uniqueness rules and stacking context notes
- MDN: @view-transition — At-rule reference for cross-document opt-in
- Can I Use: View Transitions API (single-document) — Current support breakdown across browsers