Contents

View transitions

Four exports across two entry points work together. kenspeckle holds the one that works anywhere; kenspeckle/kit holds the ones that need SvelteKit’s router, so $app/navigation never enters the main entry.

import { viewTransition } from 'kenspeckle';
import { enableViewTransitions, retreat, viewTransitionName } from 'kenspeckle/kit';
exportentryfor
enableViewTransitions/kitevery navigation, registered once
retreat/kitwhich navigations animate in reverse
viewTransitionName/kitan element that morphs across a navigation
viewTransitionmaina step within one route, such as a wizard

kenspeckle/kit expects @sveltejs/kit, an optional peer.

The contract

For the life of a transition, <html> carries one attribute, absent when idle:

data-view-transitionwritten by
forwarda navigation
retreata navigation the predicate claims, or a Back popstate
step-forwardviewTransition(update)
step-retreatviewTransition(update, { retreat: true })

Every animation is yours, keyed off that value. An unprefixed ::view-transition-old(name) rule matches both kinds, so scope it when a step and a navigation must differ:

html[data-view-transition='forward']::view-transition-old(root) {
  animation: slide-out-left 300ms;
}

Navigations

In the root layout’s script, register once:

import { enableViewTransitions } from 'kenspeckle/kit';

enableViewTransitions();

Every client-side navigation now runs inside a transition.

Direction

A Back popstate is a retreat without asking. For anything else that should animate backward, register a predicate from the component that knows, and return its disposer from an $effect:

import { retreat } from 'kenspeckle/kit';

$effect(() => retreat((navigation) => navigation.to?.route.id === '/'));

It’s a predicate rather than a flag because Kit skips beforeNavigate for a navigation begun while another is in flight, so a flag set at click time can be left behind and reverse a later navigation.

Named elements

viewTransitionName names an element for the transition it takes part in, then releases the name. Two elements holding one name silently abort the whole transition, which is why the name is claimed per transition rather than left in static CSS:

<button {@attach viewTransitionName('back-button')}>Back</button>

Claims belong to navigations only. A same-route step names nothing, so an element that should morph on a step gets a static view-transition-name in CSS instead.

Steps within a route

onNavigate never fires for a wizard advancing its own state on one URL, so call viewTransition where the state changes. In the component script:

import { viewTransition } from 'kenspeckle';

let step = $state(0);
const go = (delta: number) => viewTransition(() => (step += delta), { retreat: delta < 0 });

What all of them share

The update suspends rendering until it settles, which past half a second reads as a hang, so the transition is skipped after 600ms. With no document.startViewTransition, or under prefers-reduced-motion, the update still runs, untransitioned, and no attribute is written.