Cross-Document View Transitions: The Gotchas Nobody Mentions
This is Part 1 of a two-part series about cross-document view transitions, going over all the gotchas, from ditching the deprecated way to opt into them to a little-known 4-second timeout. Cross-Document View Transitions: The Gotchas Nobody Mentions originally handwritten and published with love on
view transitions Cross-Document View Transitions: The Gotchas Nobody Mentions Durgesh Rajubhai Pawar on May 18, 2026 I wasted an entire Saturday on this. Not a lazy Saturday either, but one of those rare, carved-out, “I’m finally going to build that thing” Saturdays. I’d seen Jake Archibald’s demos . I’d watched the Chrome Dev Summit talk. I knew cross-document view transitions were real, that you could get those slick native-feeling page transitions on plain old multi-page sites without a single framework. No React. No Astro. No client-side router pretending your multi-page application (MPA) is single-page application (SPA). Just HTML pages linking to other HTML pages, with the browser handling the animation between them. Hell yes. So I started building. And nothing worked. The first tutorial I found had me dropping <meta name="view-transition" content="same-origin"> into my <head> . Seemed simple enough. I added it to both pages, clicked my link, and… nothing. No transition. No error. Just a normal, instant page load like it was 2004. I opened DevTools, double-checked my syntax, restarted the server, tried Chrome Canary, cleared the cache. Nothing. I did what any self-respecting developer does at that point – I copied the code character by character from the blog post and pasted it in. Still nothing. I spent two hours convinced I was an idiot. Turns out that <meta> tag syntax? Deprecated. Gone. Chrome shipped it, then replaced it with a CSS-based opt-in, and half the internet’s tutorials still show the old way. Those older blog posts still rank well. They look authoritative. And they’re just wrong now. Not wrong because the authors were bad – wrong because the spec moved under everyone’s feet and nobody went back to update their posts. The other half of the tutorials I found were about same-document view transitions. SPA stuff. document.startViewTransition() called in JavaScript when you swap DOM content yourself, which is cool and useful but a completely different feature when you actually sit down to implement it. The API surface is different. The mental model is different. The gotchas are very different. And yet, Google “view transitions tutorial” and good luck figuring out which flavor you’re reading about until you’re three paragraphs deep. So if you’re here, I’m guessing you’ve been through some version of this. You tried the meta tag. It didn’t work. You tried the JavaScript API on a real multi-page site and realized it only fires within a single document. You maybe got something half-working in a demo but it fell apart the second you added real content — images stretching weird, transitions hanging for seconds with no explanation, or your CSS file turning into 200 lines of view-transition-name declarations because you have a grid of 40 product cards. You blamed yourself. It wasn’t your fa
📰Originally published at css-tricks.com
Staff Writer