View Transitions API: A Practical Guide
Same-document and cross-document view transitions explained — startViewTransition, view-transition-name, the @view-transition rule, and accessibility.
By Velloreth
Page changes are one of the rougher edges of the web. Click a thumbnail, and the entire page flashes; open a menu, and the content jumps. You can paper over this with CSS transitions on individual elements, but as soon as the update touches the DOM in more than one place, you are manually solving snapshotting, ordering, and cleanup.
The View Transitions API delegates that work to the browser. You describe what changed; the browser captures the old state, renders the new one, and animates between them. It also fixes the accessibility problems that hand-rolled approaches create — old content lingering in the accessibility tree, focus landing in the wrong place, scroll position resetting mid-animation.
There are two flavors, and they work quite differently.
| Same-document | Cross-document | |
|---|---|---|
| Trigger | document.startViewTransition() | A same-origin navigation |
| Use case | SPAs, state changes, tab switches, filters | Multi-page sites: page-to-page links |
| JavaScript | Required | None needed |
| Opt-in | Call the API | @view-transition { navigation: auto; } on both pages |
| Support | Baseline widely available (Chrome 111+, Safari 18+, Firefox 144+) | Chrome 126+, Safari 18.2+, Firefox partial |
Same-document transitions in ten lines
function updateView() {
if (!document.startViewTransition) {
renderContent(); // fallback: the old way
return;
}
document.startViewTransition(() => renderContent());
}
That is the whole contract. The browser takes a snapshot of the current state, runs your callback (which mutates the DOM), captures the result, and plays a default cross-fade. Your code stays a plain DOM update.
Three promises come back with the ViewTransition object:
updateCallbackDone— the DOM has been updated.ready— the pseudo-element tree exists and animations can start.finished— the transition is over.
ready is where customization lives, and skipTransition() is your escape hatch if the user clicks again mid-animation.
What the browser actually renders
During a transition, the browser builds a tree of pseudo-elements over the page:
::view-transition
└── ::view-transition-group(root)
└── ::view-transition-image-pair(root)
├── ::view-transition-old(root)
└── ::view-transition-new(root)
-old is a snapshot of the previous state; -new is a live rendering of the new one. Both behave like replaced elements, so familiar properties apply:
::view-transition-old(root),
::view-transition-new(root) {
animation-duration: 200ms;
animation-timing-function: ease;
}
The (root) in those names is the default — the whole page captured as one view. Everything else comes from view-transition-name:
.hero-image {
view-transition-name: hero;
}
During the transition, elements with a view-transition-name get their own -group, -image-pair, -old, and -new entries — which is how individual elements morph instead of the page merely cross-fading:
::view-transition-old(hero),
::view-transition-new(hero) {
animation-duration: 350ms;
animation-timing-function: cubic-bezier(0.2, 0.7, 0.3, 1);
object-fit: cover;
}
Uniqueness is mandatory. A view-transition-name may only match one element at a time. If duplicates exist — a list where every item reuses card, for instance — the entire transition is skipped. Generate unique names (hero-1, hero-2) or apply the name only to the element participating in the transition.
Custom animations, two ways
For anything beyond a fade, you either write CSS against the pseudo-elements (above) or drive it with the Web Animations API:
const transition = document.startViewTransition(() => renderContent());
transition.ready.then(() => {
document.documentElement.animate(
{
clipPath: [
`circle(0% at ${x}px ${y}px)`,
`circle(100% at ${x}px ${y}px)`,
],
},
{
duration: 400,
easing: 'ease-in',
pseudoElement: '::view-transition-new(root)',
},
);
});
When you animate the new view yourself, disable the default blend so the new state wipes over the old instead of fading:
::view-transition-image-pair(root) {
isolation: auto;
}
::view-transition-old(root),
::view-transition-new(root) {
animation: none;
mix-blend-mode: normal;
}
The same pattern works with clip-path, transform, or opacity — you are animating a pseudo-element, so anything compositor-friendly applies.
Cross-document: no JavaScript at all
For a multi-page site, the trigger is navigation. Both pages opt in with one rule:
@view-transition {
navigation: auto;
}
Put it in the global stylesheet and every same-origin navigation between pages that share it gets a transition. The conditions:
- Both documents are same-origin.
- No cross-origin redirect occurred during navigation.
- The navigation is a link click, form submission, or history traversal — typing in the address bar does not count.
- Both pages declare the rule (an opt-out per page is possible with
navigation: none).
Two events let you customize the edges of the transition: pageswap on the outgoing page and pagereveal on the incoming one, each exposing a viewTransition you can skip or delay.
For the common case — a shared header that should hold still while content changes — you name the same element on both pages:
.site-header {
view-transition-name: header;
}
The browser matches by name across documents. Nothing else is required.
If you are on Astro, this is what <ClientRouter /> packages up: client-side navigation between pages with transitions, plus scroll restoration, focus management, and per-element animation directives.
---
import ClientRouter from 'astro:transitions/ClientRouter';
---
<ClientRouter />
That gives you cross-page navigation with transitions on a static site, including fallbacks for browsers without the API.
Async work mid-transition
The default assumes your callback finishes synchronously. When the new state waits on data, hold the transition open:
const transition = document.startViewTransition(async () => {
const data = await fetch('/api/item/42').then((r) => r.json());
renderItem(data);
});
// keep the transition alive until the real content is ready
transition.ready
.then(() => transition.waitUntil(fetchLayout()))
.catch(() => {});
Without this, the browser captures whatever the DOM looks like at callback completion — which for a slow fetch means animating to a spinner and then popping content in afterward, the exact jarring change you were trying to avoid.
Accessibility and reduced motion
View transitions are, in one respect, better for accessibility than the manual approach: old content is captured as an image and removed from the accessibility tree rather than coexisting with the new content. That eliminates the duplicate-content and focus-confusion problems that arise when old and new DOM both exist during an animation.
What they do not solve is motion sensitivity. Ship an opt-out:
@media (prefers-reduced-motion: reduce) {
::view-transition-group(*),
::view-transition-image-pair(*),
::view-transition-old(*),
::view-transition-new(*) {
animation: none !important;
}
}
Astro’s ClientRouter handles this class of concern for you (including skipping transitions when reduced motion is requested), which is one reason to lean on it rather than hand-rolling the router.
Two more rules that keep transitions from making things worse:
- Never let the transition carry information. The content change must be understandable with animation disabled — the transition is polish on top of a change that already works.
- Watch focus. If your DOM update moves or removes the focused element, decide where focus should land and put it there in the callback. The browser captures focus as it finds it.
Three patterns worth stealing
List to detail. Name the thumbnail in the list view and the hero image in the detail view with the same name. On navigation (cross-document) or on the DOM swap (same-document), the thumbnail grows into the hero:
.card__thumb { view-transition-name: card-image; }
.detail__hero { view-transition-name: card-image; }
Because names are matched across documents, this works on a plain multi-page site with nothing but CSS. The only requirement is that each name appears once per document — so generate per-item names (card-image-42) if both views can show multiple.
Tab panels. Content swaps inside one page are the cheapest same-document case:
function selectTab(id) {
const swap = () => {
document.querySelectorAll('[role="tabpanel"]').forEach((p) => {
p.hidden = p.id !== id;
});
document.querySelectorAll('[role="tab"]').forEach((t) => {
t.setAttribute('aria-selected', t.getAttribute('aria-controls') === id);
});
};
document.startViewTransition?.(swap);
}
Give the active panel view-transition-name: active-tab and it morphs instead of the whole page cross-fading. Remember to update ARIA state inside the callback — the browser captures the DOM after your function runs, so accessibility state changes ride along with the animation.
Persistent chrome across pages. Header, nav, and footer get stable names; content gets the default root fade:
.site-header { view-transition-name: header; }
.site-nav { view-transition-name: nav; }
The effect on a multi-page site is subtle and useful: navigation and branding hold still while content changes, which is what users perceive as “fast” more than any particular easing curve.
What these share: one or two elements carry continuity, everything else cross-fades by default. Resist naming whole regions wholesale — the more you name, the more the browser has to match, and the more likely a duplicate name skips the whole transition.
When not to bother
Not every change wants a transition. Data tables where rows reshuffle, anything updating more than a couple of times per second, and interfaces where the user is acting faster than the animation can play (rapid filter toggling) all feel better instant. The API gives you skipTransition() for programmatic cases, but the simpler discipline is: if the change is small or fast, do not transition it.
Gotchas that waste an afternoon
The transition silently does nothing. Check, in order: duplicate view-transition-name values; a name on an element that only exists in one of the two states; cross-document navigation with a cross-origin redirect; navigation initiated from the address bar; navigation: auto present on only one of the two pages.
Transitions never run on the initial page load. There is no previous state to capture. Anything you see “animating in” on first load is a regular CSS animation.
Snapshots cost memory. The old state is an image of a rendered page. On extremely large DOMs this is measurable — an argument for naming specific elements rather than letting the whole document be captured when you only need one element to morph.
Only one name per element, and names must be valid custom identifiers. view-transition-name: my card is invalid; use my-card.
Nested transitions do not stack. Starting a new transition while one is running skips the current animation — the DOM update still happens, which is the behavior you want for rapid clicks.
Element-scoped transitions exist. Newer engines support element.startViewTransition() to limit the transition to one subtree. Useful when the rest of the page should not be captured at all; check support before relying on it.
Where to start
The cheapest high-value first step is cross-document transitions on a content site — one @view-transition rule, names on the header and main content, and every internal navigation smooths out with no JavaScript. Feature-detect nothing; unsupported browsers get the site as it already works.
Next comes same-document transitions for the state changes that currently jump: switching tabs, toggling a filter, expanding a row. Wrap the existing DOM update, verify the default fade, then add a view-transition-name to the one element that should morph.
Resist the urge to animate everything. The API is most convincing when a few elements carry continuity across a change and the rest cross-fades quietly — which is also, not coincidentally, what feels least like an effect and most like the page simply being fast.