View transition

The browser photographs the page before a change, lets the page after it stand above, and animates between the two. An element named in both states morphs from its old box to its new one. Across two documents it is switched on by one at-rule in each; within one document it is a call around the change. Nothing is drawn by script: the pseudo-element tree is the browser’s, and the recipe’s whole job is to say what is named, when, and how the page moves.

When to use

• A listing whose rows lead to pages: the picture and the title travel to the hero, and back. Once per navigation, over content that is already readable.
• A gallery whose thumbnails open into the picture, in place, with the browser’s own focus trap and back button.
• A list that is sorted or filtered while the reader watches.
• A language switch, which is the bilingual site’s most repeated navigation and the one where the reader most needs to stay where they were.

Do not use it for:

• A reload, a typed address, or a navigation from another origin. The browser runs no transition for those, by design.
• Text that changes language. Two headings cross-fading inside one tweening box are two words on top of each other.
• A table of data. A row that travels is a row the reader loses their place in.
• A page whose body depends on module or linked scripts running on arrival, in Firefox: the swap there runs a new body’s inline scripts only.

Rules

1. Name few things, at navigation time, and clear them after. A duplicate view-transition-name in one document cancels the whole transition. A name set in pageswap or pagereveal for the one navigation, and removed on finished and on pageshow, cannot clash: a project listed twice travels from whichever row was clicked.
2. The head script is classic and blocking. pagereveal fires before the arriving document’s first render; a module script comes after it. Measured 2026-10-09 in Chrome 155: a blocking head script that appends @view-transition { navigation: auto } itself opts the document in. No stylesheet fragment is needed.
3. What travels is said in the markup, not in a selector. data-morph="plate" and data-morph="title", inside each link on a listing and standing alone on the page it leads to.
4. Morphing pictures: height: 100%, object-fit, and overflow: clip on both snapshots. Without the clip both overflow the box mid-flight. The cure that removes the problem is one ratio at both ends.
5. A named ancestor flattens its named descendants. Restate the stacking with z-index on the groups: the plate above the root, the title above the plate, anything that must stay on top with a name of its own, a canvas included.
6. Never morph text between two languages. A language switch keeps the reader’s place instead: the first heading on screen and its distance from the top, saved on the leaving page, restored before the twin’s first render; the old text out quickly, the new in after. Recognise the twin from the page’s own link rel="alternate" hreflang elements, never from the shape of the path.
7. Keeping the place must not depend on the transition. Save it on the link’s click, restore it from the head script; a browser with no transitions restores it after its first render, as a jump.
8. Do not depend on navigation.activation. Take the destination from the clicked link and pageswap’s own activation where it exists; write the record to sessionStorage and read it on the other side.
9. One arrival per page. A page entered by transition stamps data-arrival="transition" on html and never removes it; a load effect reads that and does not play a second arrival.
10. What skips a transition is a slow first render, not a slow server. The four-second limit runs from the capture of the old page to the first render of the new. Do not hold render to wait for content without measuring.
11. Reduced motion is decided in script, once. Skip the transition in both events, or add a type under which nothing travels and the root cross-fades. The at-rule is never nested in a media query, which a host’s matchMedia override cannot see.
12. Same-document: decode before you show. The picture is decoded inside the callback so the new state is never an empty box; the page is frozen while the callback runs.
13. A change asked for mid-flight waits. Starting a second transition while one runs skips one of them and leaves a name behind. Keep the request and run it when the first lands.
14. match-element is for one document only, and it is the whole engine of a reflow: a name the browser derives from the element cannot clash and costs nothing to assign. It cannot be addressed one row at a time, so there is no stagger.
15. Chromium-only features are enhancements by feature test, never foundations: nested groups, element-scoped transitions, generated carousel controls.
16. Where only same-document transitions exist (Firefox), swap the page in. Fetch the next document and, inside one transition, replace the body, set the title and the language, push the address, run the new body’s inline scripts. Back and forward swap the same way; a page that cannot be fetched is the browser’s. The same names, types and movements serve both engines. The feature test is the PageRevealEvent constructor. See technique-compatibility.

Decisions

Tuning

Ranges are estimates; the first consumer runs its page at 384 ms and its plate at 1.15 times that.

Rest state

A plain navigation, a link that opens the picture, a list that simply changes. The same without the feature, under reduced motion (by default), on a reload, and in Firefox across documents. No recipe here hides, moves or re-parents content it did not create.

Cost

• To build: small each; the head recipe is medium, most of it the record between two documents and the four movements.
• To run: no script per frame; each named element is a texture for its old state and a live layer for its new one. Naming at navigation time keeps it to the two that travel. The browser’s default transition took 250 to 300 ms from pagereveal to finished on a fast local server. Sizes: page-morph about 3 kB gzipped, gallery-open about 2.2, listing-reflow about 1.3.
• To the reader: a navigation that is answered rather than cut, at the price of a third of a second during which input may not land. Keep it under about 400 ms.

Checklist

• The budget check passes.
• npm run check:browser: forward, held at 50 percent, the plate group is paused between the card and the hero; released, no name remains.
• npm run check:browser: back names the row that was clicked, not the first of a duplicate pair; a reload runs no transition.
• npm run check:browser: the Turkish twin opens with the same heading the same distance down.
• npm run check:browser: under reduced motion a click navigates with no transition.
• npm run check:browser: the dialog opens with the picture named and the thumbnail untouched; Escape mid-flight ends closed with nothing named; back closes it.
• npm run check:browser: rows reorder as themselves and hidden rows are never removed.
• Looked at on the stage with the hold at each stop, once per movement, and once at phone size.
• Run once in Safari and once in Firefox before it is marked passed.

Recipes

• page-morph: a picture and its title travel between two documents; the page fades, slides, irises or wipes; a language switch keeps the place.
• gallery-open: a thumbnail opens into the picture in place, and back.
• listing-reflow: rows travel to their new places when a list is sorted or filtered.

Sources

• chrome-vt-cross-document: the at-rule, the two events, the four-second limit, what navigations qualify
• chrome-vt-same-document: the same-document call and the aspect recipe
• csswg-view-transitions-1: an element is captured as painted; the pseudo-element tree is outside the accessibility tree
• chrome-element-scoped-vt: element-scoped transitions, Chromium only
• chrome-nested-vt-groups: what the flat tree loses, and that unsupported browsers ignore the property
• chrome-view-transitions-2025: match-element works within one document only
• bcd-view-transition-at-rule: support for cross-document transitions
• webdev-vt-baseline: same-document transitions in every engine
• bcd-files-2026-10-06: the conflicting Safari dates for activation, which is why nothing depends on it
• nng-animation-duration: where a transition starts to read as delay
• roselli-dont-split-words: why text is never split or morphed letter by letter