Transitions and animations

Active contributors: Rich Harris, Simon H, Dominic Gannaway

Purpose

Svelte ships built-in transitions (fade, fly, slide, scale, blur, draw, crossfade) and a built-in animation (flip). These are functions that produce CSS keyframes or per-frame tick callbacks; the runtime handles applying them to elements and coordinating their lifecycle with reactivity.

User docs: https://svelte.dev/docs/svelte/svelte-transition.

Architecture

graph TD
    SRC[".svelte source<br/><code>transition:fly</code>"] -->|compile| TC["transform-client<br/>visitor: TransitionDirective"]
    TC -->|emits call| RUN["transition() / animation()<br/><code>internal/client/dom/elements/transitions.js</code>"]
    RUN -->|invokes| FN["fly(node, params)<br/><code>src/transition/index.js</code>"]
    FN -->|returns| CFG["TransitionConfig<br/>{ delay, duration, easing, css?, tick? }"]
    CFG -->|applied as| STYLE["inline keyframes / per-frame style"]

Transitions module

packages/svelte/src/transition/index.js (~10 KB) defines all built-in transitions:

Function	What it animates
fade	Opacity from 0 to 1 (and reverse on outro).
fly	Translation + opacity.
slide	Block-axis size + padding/margin.
scale	transform: scale(...) + opacity.
blur	CSS filter: blur(...) + opacity.
draw	SVG path stroke length (uses getTotalLength()).
crossfade	Pair of send and receive functions for shared-element transitions.

Each one returns a TransitionConfig with delay, duration, easing, and either a css(t, u) function (preferred — runs on the compositor as a CSS animation) or a tick(t, u) callback (for transitions that can't be expressed in CSS, like SVG draw).

Animation module

packages/svelte/src/animate/index.js exports flip — the FLIP (First, Last, Invert, Play) algorithm for animating list reorderings. It reads the bounding rect at the start, the bounding rect at the end, and animates the delta as a CSS transform.

Easing

packages/svelte/src/easing/index.js is a single file of standard easing functions (cubicIn, cubicOut, cubicInOut, quartIn, ..., bounceOut, elasticIn, ...). Both transitions and motion utilities import from here.

Runtime glue

packages/svelte/src/internal/client/dom/elements/transitions.js (~14 KB) is the runtime that:

• Receives the TransitionConfig from the user-supplied transition function.
• Converts css into a real CSS animation (creates a <style> rule, applies it, removes it on completion).
• For tick, schedules per-frame callbacks via internal/client/loop.js and internal/client/timing.js.
• Coordinates intro and outro lifecycles with the surrounding Effect so that an outro plays to completion before the DOM node is removed.
• Implements transition: (bidirectional), in: (intro only), out: (outro only), and animate: (FLIP-style) directives.

The should_intro flag exported from packages/svelte/src/internal/client/render.js controls whether the initial render triggers intros — mount sets it to true, hydrate defaults it to false (to match server output).

Loop and timing primitives

• packages/svelte/src/internal/client/loop.js schedules a function on each requestAnimationFrame.
• packages/svelte/src/internal/client/timing.js exports a raf polyfill that falls back to setTimeout(0) outside the browser.

These same primitives are reused by the motion module for spring/tween updates.

Key source files

File	Purpose
packages/svelte/src/transition/index.js	Built-in fade, fly, slide, scale, blur, draw, crossfade.
packages/svelte/src/animate/index.js	flip animation.
packages/svelte/src/easing/index.js	Easing functions.
packages/svelte/src/internal/client/dom/elements/transitions.js	Runtime glue for transition: / animate: directives.
packages/svelte/src/internal/client/loop.js	rAF loop primitive.
packages/svelte/src/internal/client/timing.js	raf cross-environment shim.
packages/svelte/src/compiler/phases/3-transform/client/visitors/TransitionDirective.js	Compiler-side emit.

Tests

• packages/svelte/tests/runtime-runes/ and runtime-legacy/ contain transition tests. Look for sample names containing "transition", "fly", "slide".
• packages/svelte/tests/animation-helpers.js provides time-mocking helpers used across these tests.

Entry points for modification

To add a new transition, write a function in packages/svelte/src/transition/index.js that returns a TransitionConfig and export it. To change the runtime semantics (e.g., how outros block unmount), edit internal/client/dom/elements/transitions.js. The compiler doesn't need changes — transition:foo already routes through the same visitor regardless of which function is named.