Cross-Doc View Transitions: The Gotchas No person Mentions

I spent two hours satisfied I used to be an fool.

Seems that tag syntax? Deprecated. Gone. Chrome shipped it, then changed it with a CSS-based opt-in, and half the web’s tutorials nonetheless present the previous means. These older weblog posts nonetheless rank effectively. They give the impression of being authoritative. And so they’re simply incorrect now. Not incorrect as a result of the authors have been dangerous – incorrect as a result of the spec moved underneath everybody’s toes and no person went again to replace their posts.

The opposite half of the tutorials I discovered have been about same-document view transitions. SPA stuff. doc.startViewTransition() referred to as in JavaScript once you swap DOM content material your self, which is cool and helpful however a very totally different characteristic once you truly sit all the way down to implement it. The API floor is totally different. The psychological mannequin is totally different. The gotchas are very totally different. And but, Google “view transitions tutorial” and good luck determining which taste you’re studying about till you’re three paragraphs deep.

So in the event you’re right here, I’m guessing you’ve been by means of some model of this. You tried the meta tag. It didn’t work. You tried the JavaScript API on an actual multi-page website and realized it solely fires inside a single doc. You possibly acquired one thing half-working in a demo however it fell aside the second you added actual content material — photographs stretching bizarre, transitions hanging for seconds with no rationalization, or your CSS file turning into 200 strains of view-transition-name declarations as a result of you will have a grid of 40 product playing cards. You blamed your self. It wasn’t your fault. The documentation ecosystem round this characteristic is a multitude proper now, and the spec has been a transferring goal.

That is Half 1 of a two-part sequence, and it’s the article I want existed on that Saturday. We’re going to cowl the precise present method to decide in with @view-transition in CSS (not the meta tag, not JavaScript), then dig into the 4-second timeout that may silently kill your transitions on sluggish pages and debug it, then repair the side ratio warping that makes each image-heavy transition appear like a enjoyable home mirror, and eventually get a correct deal with on the pagereveal and pageswap occasions that provide you with programmatic management over the entire lifecycle.

In Half 2, we’ll deal with the scaling downside – deal with view-transition-name throughout dozens or a whole bunch of components with out your stylesheet changing into a catastrophe, the distinction between view-transition-name and view-transition-class, just-in-time naming patterns, and doing prefers-reduced-motion the proper means.

Seize espresso. Perhaps a refill. This one’s dense and I’m not going to waste your time, however there’s a number of floor right here and none of it’s apparent.

The Outdated Manner is Useless

/* THIS is the present opt-in - goes in your CSS */
@view-transition {
  navigation: auto;
}

Right here’s the minimal setup. Two HTML information, one CSS rule on every. Be aware that, as of 2026, cross-document view transitions are supported in Chromium-based browsers and Safari 18.2+. Firefox help is in progress as I’m scripting this.

That’s it. Two HTML information. One CSS rule on every. Click on a hyperlink between them in a supporting browser (like trendy Chromium or Safari 18.2+) and also you get a easy cross-fade. No JavaScript. No meta tags. No construct step. The browser snapshots the previous web page, snapshots the brand new web page, and animates between them robotically.

Now, why did the spec transfer from a meta tag to a CSS at-rule? It wasn’t arbitrary.

The meta tag was a blunt instrument. It was on or off for the whole web page. You couldn’t say “allow transitions on desktop however not on cellular the place the animations really feel janky on low-end {hardware}.” You couldn’t conditionally decide in based mostly on consumer preferences. It was simply… there, or not.

The CSS strategy opens all of that up:

/* Solely allow transitions if the consumer hasn't requested for lowered movement */
@media (prefers-reduced-motion: no-preference) {
  @view-transition {
    navigation: auto;
  }
}

/* Solely allow on viewports broad sufficient for the animation to really feel good */
@media (min-width: 768px) {
  @view-transition {
    navigation: auto;
  }
}

That’s an actual improve. You get the identical conditional energy you have already got with each different CSS characteristic. Media queries, @helps, no matter scoping logic you need — all of it simply works as a result of the opt-in lives the place your kinds reside.

There’s additionally a subtlety that issues: the CSS rule could be totally different on the previous web page versus the brand new web page. Each pages have to decide in for the transition to fireplace. If Web page A has @view-transition { navigation: auto; } however Web page B doesn’t, you get no transition. That is truly helpful – it means your 404 web page or your login redirect can skip transitions with none JavaScript coordination.

Yet another factor price noting right here: navigation: auto solely kicks in for user-initiated, same-origin navigations. If the consumer clicks a daily hyperlink or hits the browser’s Again button, you get a transition. However window.location.href = "https://css-tricks.com/someplace" set programmatically, or a cross-origin hyperlink, or a type submission with a POST? No transition. The browser is deliberately conservative about when it fires, and actually that’s the proper name. You don’t desire a fancy cross-fade on a POST request that’s making a cost.

Look, in the event you’ve been following an outdated tutorial and your transitions simply silently don’t work, that is virtually definitely why. The meta tag shipped in Chrome 111, acquired a number of months of real-world use, after which the Chrome group deprecated it in favor of the CSS at-rule beginning round Chrome 126. No console warning. No error. The previous syntax simply quietly does nothing now. Truthfully, a deprecation warning in DevTools would’ve saved me (and doubtless you) a number of grief, however right here we’re.

Swap the meta tag for the CSS rule. That’s the first step. Every little thing else on this article builds on it.

Your Transition Will Randomly Die, and Right here’s Why

// Drop this in your pages to see what's truly taking place
window.addEventListener("pagereveal", (occasion) => {
  if (!occasion.viewTransition) {
    console.log(
      "No view transition - web page did not decide in or browser skipped it",
    );
    return;
  } // That is the one which'll save your sanity

  occasion.viewTransition.completed
    .then(() => console.log("Transition accomplished ✅"))
    .catch((err) => {
      // You may see "TimeoutError" right here and nowhere else
      console.error("Transition killed:", err.title, err.message);
    });
});

Right here’s the factor no person places of their weblog publish: cross-document view transitions have a tough 4-second timeout. If the brand new web page doesn’t attain a state the browser considers “renderable” inside 4 seconds of the navigation beginning, the transition simply… dies. No animation. No cross-fade. The brand new web page snaps in like view transitions don’t exist. And except you’ve acquired that pagereveal listener wired up and your console open, you gained’t get any indication that something went incorrect.

4 seconds sounds beneficiant — till it isn’t.

Take into consideration what occurs on an actual website. Your web page masses. The HTML arrives, positive, that’s quick. However possibly you’ve acquired an enormous hero picture that’s render-blocking. Perhaps there’s a sluggish API name that your server waits on earlier than sending the response – a product web page hitting a listing service, a dashboard ready on analytics knowledge, something with server-side rendering that truly does work earlier than responding. Perhaps you’re on a good connection however the web page has three internet fonts loading from Google Fonts with font-display: block. Any of those can push you previous that 4-second window, and the timeout doesn’t care why you’re sluggish. It simply cuts the transition.

The actually maddening half? It really works completely on localhost. Your dev server responds in 80ms. The transition is butter. You deploy to manufacturing, your server’s cold-starting a lambda or your CDN cache missed, and abruptly customers get zero transitions on the primary click on. You’ll be able to’t reproduce it regionally. You begin questioning every part.

// It's also possible to catch this on the OLD web page utilizing `pageswap`
// Helpful for cleanup or logging which navigations fail
window.addEventListener("pageswap", (occasion) => {
  if (occasion.viewTransition) {
    occasion.viewTransition.completed.catch((err) => {
      // Log it, ship it to your analytics, no matter
      console.warn("Outgoing transition aborted:", err.title);
    });
  }
});

So, what do you truly do about it?

Choice one: make your web page quicker. I do know, groundbreaking recommendation. However significantly – in case your cross-document transition is dying, that’s a sign your web page load is genuinely sluggish. The timeout is appearing as a efficiency canary. Take a look at your Efficiency tab in DevTools, run a Lighthouse audit (which can not be good), work out what’s blocking first render. This isn’t view-transition-specific recommendation, however the timeout forces you to care about it.

Choice two is extra fascinating, and it’s the factor I want I’d recognized about instantly.

This:

…tells the browser: “Don’t take into account this web page renderable till a component matching #hero is within the DOM.” That feels like it might make issues slower, and in a means it does – it delays first paint. However for view transitions, that’s precisely what you need: you’re telling the browser to carry the snapshot till the vital content material is definitely there, fairly than snapping a screenshot of a half-loaded web page or, worse, timing out as a result of some picture within the footer continues to be downloading and blocking one thing.

It’s a trade-off. You’re selecting a barely delayed, however easy, transition over a quick, but-broken, one.

Truthfully, the 4-second restrict might be the proper name from the browser’s perspective. You don’t desire a consumer clicking a hyperlink and watching a frozen web page for 10 seconds whereas the browser waits to do a elaborate animation. In some unspecified time in the future, simply displaying the rattling web page is healthier than a reasonably transition. However I want Chrome would floor the timeout extra visibly – a DevTools warning, a efficiency marker, one thing. Proper now it fails silently and that’s the entire downside.

Yet another factor price figuring out: the timeout clock begins when navigation begins, not when the brand new web page’s HTML begins arriving. Community latency counts. The Time to First Byte (TTFB) Core Internet Very important counts. In case your server takes 2 seconds to reply and your web page takes 2.5 seconds to render after that, you’re over the restrict despite the fact that neither half feels sluggish by itself.

A debugging tip that’s saved me greater than as soon as: Chrome’s DevTools has an Animations panel (it’s underneath “Extra instruments” in the event you don’t see it) that may truly seize view transitions in motion. You’ll be able to sluggish them all the way down to 10% velocity, replay them, and examine the pseudo-element tree mid-animation. It’s not apparent that it really works for view transitions, however it does. Between that and the pagereveal listener above, you’ll be able to diagnose most timeout points fairly shortly.

Put that pagereveal listener in early. Watch your console throughout testing. You’ll thank your self later.

Why Your Pictures Look Like Taffy

This one’s simpler to point out with a same-document demo first (since you’ll be able to truly run it in a single file), however the issue and the repair are equivalent for cross-document transitions.

Run that. Click on the picture. Watch the canine flip into foolish putty.

The picture itself has object-fit: cowl on either side. The thumbnail seems positive, the hero seems positive. However throughout the transition? The browser doesn’t transition your component. It takes a screenshot of the previous state, takes a screenshot of the brand new state, and morphs between them. These screenshots are flat raster photographs. Your rigorously utilized object-fit? Gone. The browser is simply scaling a bitmap from one field dimension to a different, and when a 150×150 sq. will get stretched right into a 600×300 rectangle, you get taffy.

Right here’s the repair:

/* THE FIX - goal the transition pseudo-elements instantly */
::view-transition-old(hero-img),
::view-transition-new(hero-img) {
  /* Deal with the snapshot like a picture in a container - crop, do not stretch */
  object-fit: cowl;
  overflow: hidden;
}

That’s the entire thing. Two properties on two pseudo-elements.

What’s truly taking place: the browser generates a tree of pseudo-elements for each named transition. For a component with view-transition-name: hero-img, you get this construction throughout the animation:

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

The ::view-transition-group easily animates its width and top from the previous dimensions to the brand new ones. That’s the morphing rectangle you see. Inside it, the previous and new pseudo-elements maintain the precise bitmap snapshots, and by default they’re set to object-fit: fill – that means “stretch to fill no matter field you’re in, side ratio be damned.”

Switching to object-fit: cowl tells these snapshots to keep up their side ratio and crop the overflow as an alternative. Similar psychological mannequin as a background picture with background-size: cowl. The transition nonetheless animates the field from sq. to rectangle (or no matter your shapes are), however the picture inside crops gracefully as an alternative of warping.

You might additionally use object-fit: include right here in the event you’d fairly see the total picture with letterboxing as an alternative of cropping. It depends upon what seems proper in your content material. However cowl is what you’ll need 90% of the time, particularly for product photographs and hero photographs.

For cross-document transitions, the CSS is equivalent – you simply put it in each pages’ stylesheets:

/* This works cross-document. Similar selectors, similar repair. */
/* Put it in your shared CSS file that each pages load. */
@view-transition {
  navigation: auto;
}

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

/* It's also possible to management 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);
}

Truthfully, I believe object-fit: cowl needs to be the default on these pseudo-elements as an alternative of fill. I get why the spec selected fill – it’s predictable, it matches what object-fit defaults to on changed components in every single place else in CSS – however in follow, how typically do you truly need a stretched bitmap throughout a transition? Nearly by no means. You’ll be including this override on mainly each picture transition you construct.

Yet another variant that’s helpful when the side ratios are wildly totally different – say a tall portrait thumbnail transitioning right into a cinematic widescreen hero:

/* High quality-tune the place the crop occurs on both sides of the transition */
::view-transition-group(hero-img) {
  overflow: hidden;
  border-radius: 8px; /* maintain it fairly mid-flight */
}

::view-transition-old(hero-img) {
  object-fit: cowl;
  object-position: middle middle;
}

::view-transition-new(hero-img) {
  object-fit: cowl;
  object-position: middle prime; /* maintain the highest of the hero seen */
}

You’ll be able to set totally different object-position values on previous versus new, which helps you to management the place the crop occurs on both sides of the transition independently. The previous thumbnail would possibly look greatest cropped from middle. The brand new hero would possibly have to anchor to the highest. Combine and match.

This took me an embarrassingly very long time to determine. The repair is 2 strains of CSS, however in the event you don’t know the pseudo-element tree exists, you don’t even know what to focus on. Now you do.

The Two Occasions That Tie it All Collectively

You’ve already seen pagereveal and pageswap present up within the code above, however let’s take a step again and speak about what they really are. Understanding these two occasions goes to be vital, as a result of in Half 2 we’ll lean on them closely for the just-in-time naming sample that makes view transitions truly scale.

Cross-document view transitions occur throughout two pages that don’t have any JavaScript connection to one another. Web page A doesn’t learn about Web page B’s DOM. For the reason that previous and new pages don’t have any method to talk instantly, these occasions are your solely method to coordinate the transition on either side. Web page B didn’t exist when Web page A was operating. So how do you coordinate something? How do you determine which components to call, or customise the transition based mostly on the place the consumer is heading?

That’s what these two occasions are for. They’re your hooks into the transition lifecycle, one on both sides of the navigation.

pageswap fires on the outgoing web page, proper earlier than it will get changed. That is your final probability to the touch the previous web page’s DOM earlier than the browser snapshots it. The occasion offers you two key properties:

• occasion.viewTransition: the ViewTransition object for this navigation, or null if no transition is occurring.
• occasion.activation: a NavigationActivation object that tells you the place the consumer goes.

That activation property is the actually helpful one. occasion.activation.entry.url offers you the vacation spot URL, and occasion.activation.navigationType tells you whether or not it’s a push, exchange, traverse (again/ahead), or reload. This implies you’ll be able to customise the outgoing facet of the transition based mostly on the vacation spot. On a product itemizing web page, for instance, you’ll be able to examine which product the consumer clicked, discover the matching card, and assign a view-transition-name to only that component proper earlier than the snapshot occurs.

pagereveal fires on the incoming web page, proper after the web page turns into energetic however whereas the transition continues to be operating. That is your probability to arrange the brand new facet. The occasion offers you:

• occasion.viewTransition: similar deal, the ViewTransition object or null.

On the incoming web page, you examine the place the consumer got here from utilizing navigation.activation.from.url (through the Navigation API), and also you learn the present URL from window.location. Between these two items of knowledge, you recognize precisely what sort of navigation simply occurred and might arrange the incoming web page’s transition components accordingly.

Right here’s the total lifecycle so as:

1. Consumer clicks a hyperlink on Web page A.
2. pageswap fires on Web page A. That is your window to call components and customise outgoing state.
3. Browser snapshots the previous web page (capturing any named components).
4. Navigation occurs, new web page masses.
5. pagereveal fires on Web page B. You’ll be able to title components, customise incoming state.
6. Browser snapshots the brand new web page.
7. Transition animates between the 2 snapshots.
8. viewTransition.completed resolves (or rejects) on either side.

Three issues to remember with these occasions:

First, all the time guard with if (!occasion.viewTransition) return on the prime of your handlers. pagereveal truly fires on each navigation – preliminary web page load, again/ahead, the works – not simply view transitions. If there’s no transition taking place, occasion.viewTransition will probably be null, and your handler ought to bail out gracefully. These handlers are transition sugar, not software logic. By no means put unwanted side effects in them that you simply want for the web page to work.

Second, pageswap solely fires if the previous web page opted into view transitions and the navigation is same-origin. If the consumer middle-clicks to open in a brand new tab, or the navigation goes cross-origin, the occasion both gained’t fireplace or occasion.viewTransition will probably be null. That’s positive, your guard clause handles it.

Third, and that is simple to miss: each occasions provide you with entry to viewTransition.completed, which is a promise that resolves when the transition completes or rejects if one thing goes incorrect (like a timeout). All the time use this for cleanup, as in eradicating view-transition-name values you set dynamically, resetting state, no matter. Stale names from a earlier transition will destroy your subsequent one.

We’ve been utilizing these occasions calmly to date – a pagereveal listener to catch timeouts, a pageswap listener for logging. In Half 2 of this little sequence, they grow to be the spine of the entire scaling technique. Keep tuned.

What’s Subsequent

That covers the three gotchas that’ll chunk you first: the deprecated meta tag that silently does nothing, the 4-second timeout that kills transitions with out telling you, and the picture distortion that turns each side ratio change right into a enjoyable home mirror. Plus the 2 occasions that provide you with hooks into the entire lifecycle.

In Half 2, we’ll deal with the scaling downside. While you’ve acquired a grid of 48 product playing cards and every one wants a singular view-transition-name, how do you retain your CSS from exploding? The reply includes view-transition-class (which is totally different from view-transition-name in ways in which aren’t apparent), a just-in-time naming sample utilizing the pageswap and pagereveal occasions we simply coated. And one important observe: we’ll cowl prefers-reduced-motion in Half 2, however in the event you take nothing else from this sequence, take this: animations can actually make individuals bodily nauseous. All the time examine that desire and respect it.

The gotchas are behind you. Now it’s time to make it scale.