Knowledge · Guidelines · sveltekit
View Transition Navigation
Manage video playback, DOM observation, and navigation state during SvelteKit client-side View Transitions
Metadata
sveltekit sveltekit
Description
SvelteKit uses the View Transitions API (document.startViewTransition + onNavigate) for
client-side page transitions. During the ~250ms snapshot+animate phase, the browser freezes
rendering and silently drops or defers certain DOM operations:
- video.play() is silently rejected (no error thrown, promise resolves but playback never starts)
- document.getElementById() may return null for elements that exist in the new DOM but aren't
yet mounted in the live document tree
- IntersectionObserver entries report stale intersection ratios from the pre-transition DOM
- Scroll position may not reflect the new page state
This guideline defines the patterns every component must follow when interacting with these APIs
during client-side navigation.
Established from PR #326 (v0.15.9) — VideoStream safePlay() and ContentSidebar deferred scroll-spy.
Rules
- VTN-1 — Never call video.play() directly — always use the safePlay() retry pattern
- VTN-2 — DOM element lookups in $effect must use deferred resolution with retry
- VTN-3 — Use 350ms as the standard retry delay for View Transition recovery
- VTN-4 — All cleanup functions in $effect must clear retry timers AND disconnect observers
- VTN-5 — Navigation active state (sidebar, footer, navbar) must derive from SvelteKit stores, not DOM state
- VTN-6 — HLS video components must handle re-initialization on client-side navigation
- VTN-7 — Footer and navbar active link state must use the same isPathMatch() logic as ContentSidebar