The most common reason a cross-document transition silently fails is stale documentation. The original opt-in was <meta name="view-transition" content="same-origin">, shipped in Chrome 111, in use for a few months, then deprecated starting around Chrome 126. Adding that tag today produces no transition, no console warning and no error — the old syntax simply does nothing. A large share of well-ranking tutorials still show it, which is how a straightforward setup can consume an afternoon.

The second trap is mixing up features. Material that discusses document.startViewTransition() covers same-document transitions: JavaScript you call yourself after swapping DOM content. Cross-document transitions are a different API surface, a different mental model and different failure modes, even though search results for "view transitions" blend the two until several paragraphs in. None of it is the developer's fault; the spec has been a moving target.

Opting in with CSS

<!-- THIS IS DEPRECATED - stop copying this from old tutorials -->
<meta name="view-transition" content="same-origin">
/* THIS is the current opt-in - goes in your CSS */
@view-transition {
  navigation: auto;
}

The replacement is a CSS at-rule: @view-transition { navigation: auto; }. Two HTML files, one rule in each stylesheet, and a link between them produces a smooth cross-fade in a supporting browser. No JavaScript, no meta tags, no build step. The browser snapshots the old page, snapshots the new page and animates between the two. As of 2026, cross-document view transitions are supported in Chromium-based browsers and Safari 18.2+; Firefox support is in progress.

The move from a meta tag to an at-rule was not arbitrary. The meta tag was all-or-nothing for the page: no way to enable transitions on desktop while skipping them on low-end mobile hardware, and no way to respond to user preferences. Because the opt-in now lives with the rest of your styles, ordinary conditionals apply:

/* Only enable transitions if the user hasn't asked for reduced motion */
@media (prefers-reduced-motion: no-preference) {
  @view-transition {
    navigation: auto;
  }
}
/* Only enable on viewports wide enough for the animation to feel good */
@media (min-width: 768px) {
  @view-transition {
    navigation: auto;
  }
}

Media queries, @supports and any scoping logic you like all work as they do elsewhere in CSS.

When a transition fires

Both pages must opt in. If page A carries the rule and page B does not, no transition happens. That asymmetry is a feature: a 404 page or a login redirect can skip transitions with zero JavaScript coordination.

Even with both sides opted in, navigation: auto only applies to user-initiated, same-origin navigations. Clicking a regular link or pressing the browser's Back button animates. A programmatic window.location.href = "/somewhere", a cross-origin link, or a form submitted with POST does not. The browser is deliberately conservative here, which keeps a cross-fade off a payment-creating request.

The four-second cutoff

// Drop this in your pages to see what's actually happening
window.addEventListener("pagereveal", (event) => {
  if (!event.viewTransition) {
    console.log(
      "No view transition - page didn't opt in or browser skipped it",
    );
    return;
  } // This is the one that'll save your sanity

  event.viewTransition.finished
    .then(() => console.log("Transition completed ✅"))
    .catch((err) => {
      // You'll see "TimeoutError" here and nowhere else
      console.error("Transition killed:", err.name, err.message);
    });
});

Cross-document view transitions carry a hard 4-second timeout. If the new page does not reach a state the browser considers renderable within four seconds of navigation start, the transition is abandoned: no cross-fade, the new page snaps in, and nothing appears in the console unless you have a pagereveal listener in place and DevTools open.

Four seconds is easy to exceed on a real site. A render-blocking hero image, a server-rendered response that waits on an inventory or analytics service, or three web fonts served with font-display: block can each blow the budget, and the timeout does not care about the cause. The clock starts at navigation start, not when the new HTML begins arriving, so network latency counts — TTFB is part of the four seconds. A two-second server response plus two and a half seconds to render is over the limit even though neither half looks slow alone. It also explains the classic deployment surprise: an 80ms dev server animates flawlessly, while a cold lambda or a CDN cache miss gives users no transition on the first click, unreproducible locally.

// You can also catch this on the OLD page using `pageswap`
// Useful for cleanup or logging which navigations fail
window.addEventListener("pageswap", (event) => {
  if (event.viewTransition) {
    event.viewTransition.finished.catch((err) => {
      // Log it, send it to your analytics, whatever
      console.warn("Outgoing transition aborted:", err.name);
    });
  }
});

Working within the timeout

Treat the timeout as a performance canary. If transitions are dying, first render is being blocked — check the Performance panel and run a Lighthouse audit (which may not tell the whole story) to find what is holding it up.

The more interesting lever is the blocking attribute:

<!-- Note: rel="expect" is newer and browser support is rolling out -->
<link rel="expect" href="#hero" blocking="render">
<link rel="expect" href="#hero" blocking="render">

This tells the browser not to consider the page renderable until an element matching #hero exists in the DOM. It delays first paint, which sounds counterproductive but is the point: the browser holds the snapshot until the important content is present instead of capturing a half-loaded page or timing out. You are trading a slightly delayed, smooth transition for a fast, broken one. Suppose the browser's position deserves some sympathy — nobody wants a ten-second frozen page while an animation waits. The real complaint is visibility: the failure is silent, with no DevTools warning and no performance marker.

For diagnosis, the Animations panel (under "More tools") captures view transitions. You can slow them to 10% speed, replay them and inspect the pseudo-element tree mid-animation. It is not obvious that the panel handles view transitions, but it does. Combined with an early pagereveal listener and an open console during testing, most timeout problems can be traced quickly.

Image Warping During Transitions

Images are where the default behavior bites hardest, and the failure mode is easiest to see in a same-document demo — though the cause and the cure apply equally to cross-document transitions.

Set object-fit: cover on both sides and every static state looks correct. The breakage happens mid-animation: the browser never animates your <img> element. It snapshots the old state, snapshots the new state, and interpolates between two flat rasters. object-fit is not part of that interpolation. A 150×150 square stretched to 600×300 is just a bitmap being scaled, which is why it looks like taffy.

The correction is two properties on two pseudo-elements:

/* THE FIX - target the transition pseudo-elements directly */
::view-transition-old(hero-img),
::view-transition-new(hero-img) {
  /* Treat the snapshot like an image in a container - crop, don't stretch */
  object-fit: cover;
  overflow: hidden;
}

Each named transition generates a pseudo-element tree. For view-transition-name: hero-img, that structure looks like this while the animation runs:

::view-transition
└── ::view-transition-group(hero-img)
    ├── ::view-transition-old(hero-img)
    └── ::view-transition-new(hero-img)

::view-transition-group animates width and height from the old dimensions to the new ones — that is the morphing rectangle you see. The old and new children hold the bitmap snapshots and default to object-fit: fill, i.e. stretch to the box regardless of aspect ratio. Switching them to cover preserves aspect ratio and crops the overflow, much like background-size: cover. The box still animates between shapes; the content inside now degrades gracefully. contain is the alternative when you would rather letterbox than crop. For cross-document transitions the CSS is unchanged — place it in both pages' stylesheets:

/* This works cross-document. Same selectors, same fix. */
/* Put it in your shared CSS file that both pages load. */
@view-transition {
  navigation: auto;
}

::view-transition-old(hero-img),
::view-transition-new(hero-img) {
  object-fit: cover;
}

/* You can also control the animation timing on the group */
::view-transition-group(hero-img) {
  animation-duration: 0.4s;
  animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
}

When the aspect ratios diverge sharply — a portrait thumbnail expanding into a widescreen hero — controlling the crop per side helps:

/* Fine-tune where the crop happens on each side of the transition */
::view-transition-group(hero-img) {
  overflow: hidden;
  border-radius: 8px; /* keep it pretty mid-flight */
}

::view-transition-old(hero-img) {
  object-fit: cover;
  object-position: center center;
}

::view-transition-new(hero-img) {
  object-fit: cover;
  object-position: center top; /* keep the top of the hero visible */
}

Different object-position values on old and new let you anchor each snapshot independently: center for the thumbnail, top for the hero.

The pseudo-element tree is the part that trips people up. Without knowing it exists, there is nothing obvious to target, and the fix stays undiscovered.

The Lifecycle Events on Each Side

Two events bracket a cross-document navigation, and they matter because Page A and Page B share no JavaScript context. When the old page runs, the new page does not exist yet, so these events are the only coordination points.

pageswap fires on the outgoing page immediately before replacement — the last moment to modify its DOM before snapshotting. It exposes:

  • event.viewTransition — the ViewTransition object for this navigation, or null if none is running.
  • event.activation — a NavigationActivation describing where the user is going.

event.activation.entry.url yields the destination URL, and event.activation.navigationType reports push, replace, traverse (back/forward) or reload. That lets the outgoing side adapt to the destination: on a listing page, read which product was clicked, locate the matching card, and assign a view-transition-name to that element only.

pagereveal fires on the incoming page after it becomes active, while the transition is still in flight, giving you the same event.viewTransition property. There you combine navigation.activation.from.url (via the Navigation API) with window.location to determine the navigation's origin and configure the incoming side accordingly.

In sequence: a link click fires pageswap on A; the browser snapshots A with any named elements; navigation and load occur; pagereveal fires on B; the browser snapshots B; the snapshots animate; then viewTransition.finished settles on both sides.

Guardrails for These Handlers

Bail out early. Begin every handler with if (!event.viewTransition) return. pagereveal fires on every navigation, including the initial load and back/forward, not just transitions; with no transition running, event.viewTransition is null. Treat these handlers as enhancement only — no side effects the page depends on.

Absence is normal. pageswap fires only when the outgoing page opted into view transitions and the navigation is same-origin. Middle-clicking into a new tab or navigating cross-origin means either no event or a null transition. The guard clause covers both.

Clean up via the promise. Both events expose viewTransition.finished, which resolves on completion or rejects on failure (a timeout, for instance). Use it to remove names you assigned dynamically and reset state; leftover names from a prior transition will corrupt the next one.

Open Items

The first-order problems: a deprecated meta tag that fails silently, a 4-second timeout that aborts transitions without notice, and image stretching on any aspect-ratio change — plus the two events that provide lifecycle hooks. Motion accessibility is not minor: animations can make people physically nauseous, so the prefers-reduced-motion preference must be checked and respected.