1. wait for image decode
large hero image must finish decoding before the new state animates in.
state A
demo · v144
Extension Recipes
Four real reasons authors call waitUntil(): hold the pseudo-tree through an image decode, through a fetch, through a Lottie/Web Animations sequence, or through a network handshake. Each recipe fires a transition and shows the timing — with and without the wait.
document.startViewTransition: checking…
2. wait for a fetch
new state depends on a server call. Don't start the animation with stale content.
state A
3. wait for a JS animation
a Web Animations sequence (Lottie, particle effect) must complete before tearing down.
state A
4. timeout race
wait for X but skip if it takes more than 800ms — graceful degradation.
state A
the API
const t = document.startViewTransition(() => updateDOM());
// recipe 1: hold for image decode
t.ready.then(() => {
t.waitUntil(image.decode());
});
// recipe 4: timeout race
t.waitUntil(Promise.race([
loadHero(),
new Promise((r) => setTimeout(r, 800))
]));