Motion

Active contributors: Rich Harris, Simon H

Purpose

svelte/motion provides physics-based reactive utilities — Spring (force-driven oscillation) and Tween (eased interpolation) — plus the deprecated function-style spring() and tweened() stores. Both produce a .current value that you can read in templates to drive transitions or layout values.

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

Files

packages/svelte/src/motion/
├── index.js          # public exports
├── spring.js         # Spring class + legacy `spring()` store
├── tweened.js        # Tween class + legacy `tweened()` store
├── utils.js          # is_date helper
├── public.d.ts       # public types
└── private.d.ts      # internal TickContext

Spring

packages/svelte/src/motion/spring.js (~10 KB) implements the modern Spring class plus the deprecated spring() function. Spring:

• Takes an initial value plus { stiffness, damping, precision } options.
• Exposes .current (read-only reactive getter) and .target (writable target).
• Each frame, tick_spring (in the same file) integrates a Hooke's-law step from the previous value toward the target, applying damping for stability.
• .set(value, { instant?, preserveMomentum? }) sets the target with optional overrides.

The frame loop uses loop from packages/svelte/src/internal/client/loop.js and raf from internal/client/timing.js. The reactive value is a state(...) Source from internal/client/reactivity/sources.js, which means .current participates in the reactivity engine like any other source.

Special cases:

• Date values: tick uses milliseconds since epoch.
• Array and plain object values: tick_spring recurses element-by-element.

Tween

packages/svelte/src/motion/tweened.js (~7 KB) implements Tween and the deprecated tweened() function. Tween interpolates between values over duration ms with an easing function (default linear from svelte/easing). Its frame logic is the same shape as Spring but without physics — just a normalised progress value.

Tween.of(getter) creates a Tween that automatically retargets whenever the getter changes — convenient for animating a value derived from $state.

Public API

packages/svelte/src/motion/index.js:

export { Spring, spring } from './spring.js';
export { Tween, tweened } from './tweened.js';

Public types (public.d.ts)

• SpringOptions — stiffness, damping, precision.
• SpringUpdateOptions — instant, preserveMomentum.
• Spring — { current, target, set(...), animation }.
• Tweened (deprecated alias of legacy tweened).
• Tween.

Tests

packages/svelte/tests/motion/ contains unit tests that mock raf (via the test helpers in tests/animation-helpers.js) to step the simulation deterministically.

Key source files

File	Purpose
packages/svelte/src/motion/spring.js	Spring and legacy spring().
packages/svelte/src/motion/tweened.js	Tween and legacy tweened().
packages/svelte/src/motion/utils.js	is_date.
packages/svelte/src/motion/public.d.ts	Public types.

Entry points for modification

To add another motion primitive (e.g., a damped follower or a stepper), drop a new file under src/motion/, export a class with a .current getter backed by a Source from internal/client/reactivity/sources.js, drive frames with loop() from internal/client/loop.js, and re-export from motion/index.js. Match the shape of Spring and Tween so users can compose them with the same patterns.