``` `x.current` tracks via `$state`, so reads inside templates, `$derived`, and `$effect` re-run automatically when the spring updates. `$x` is the Svelte 4–style auto-subscribe path — it works because the spring exposes a `.subscribe()` shim, but `.current` is preferred for new code. ## Usage ### From an initial value Pass a number or unit string to create a spring with that initial value: ```svelte

scale.set(1.2)} onpointerleave={() => scale.set(1)} > Hover to scale

``` ### Following another motion value Pass another `MotionValue` (e.g. from `useMotionValue`, `useScroll`, or another `useSpring`) and the spring will animate toward whatever that source emits: ```svelte target.set(+e.currentTarget.value)} />

Smooth

``` ### Following a Svelte readable store For interop with hooks that still return Svelte stores (`useScroll`, `useTime`), pass the store directly — it's bridged into a motion value internally: ```svelte

``` ### With unit strings `useSpring` preserves unit suffixes like `px`, `deg`, `vh`, `%`: ```svelte ``` ## Configuration Customize the spring physics by passing options: ```svelte ``` ### Defaults | Option | Default | Notes | | ------------- | ------- | ------------------------------------------------------ | | `stiffness` | `100` | Higher = snappier | | `damping` | `10` | Higher = less oscillation | | `mass` | `1` | Higher = more lethargic | | `restDelta` | `0.001` | Position threshold to settle | | `restSpeed` | `0.01` | Velocity threshold to settle | | `velocity` | `0` | Initial velocity | > **Note:** These defaults match [motion-dom](https://motion.dev/) — and React framer-motion's `useSpring`. They differ from `useSpring`'s prior svelte-motion defaults (`170` / `26`); pass explicit options if you need the older feel. ### Duration-based options When you'd rather tune by feel than by physics constants, use the duration API: | Option | Default | Notes | | ----------------- | ------- | ------------------------------------------------------------------------------------ | | `duration` | `800`ms | Total animation duration | | `visualDuration` | — | Visual settle time (overrides `duration` when set); easier to coordinate with tweens | | `bounce` | `0.3` | `0` = no bounce, `1` = very bouncy | Setting `stiffness`, `damping`, or `mass` overrides `duration` / `bounce`. ### `skipInitialAnimation` When following a source motion value, the spring normally animates from its initial value to whatever the source emits first. For scroll-restoration or back-navigation scenarios where the first emit is the "current" position rather than a target, set `skipInitialAnimation: true` so the spring jumps to the first value and only animates on subsequent updates: ```svelte ``` ## Methods ### `set(value)` Animate toward a new target value: ```svelte ``` If the spring is mid-animation, the existing velocity carries over into the new target — no visible discontinuity. ### `jump(value)` Immediately set the value without animation: ```svelte ``` Useful for resetting state or initializing to a known position. ### `get()` Read the current value imperatively: ```svelte ``` Prefer `x.current` inside reactive scopes (templates, `$derived`, `$effect`); use `.get()` in event handlers and other one-shot reads. ### `on(event, callback)` Subscribe to motion value events. Returns an unsubscribe function. ```svelte ``` ### `destroy()` Tear down the spring early. Normally not needed — the spring auto-cleans up when its surrounding component unmounts. ## How it works `useSpring` returns a `MotionValue` from `motion-dom` (the same primitive used by every other motion value in this library). The spring physics are computed by motion-dom's `attachFollow` + `JSAnimation` — the same engine React framer-motion uses, so behavior, defaults, and option semantics are 1:1. The Svelte 5 layer adds: - A `.current` getter backed by `$state`, kept in sync with the motion value's `change` event so reads inside reactive scopes track automatically. - A `.subscribe(run)` shim implementing the Svelte readable store contract, so legacy `$store` syntax and store-consumers (`useTransform` function form, `useVelocity`, `derived(...)`, etc.) keep working. - Lifecycle binding via `$effect`, so the spring auto-cleans when the component unmounts. ## Performance - **On-demand:** The animation loop only runs while the spring is in motion. - **Auto-settle:** Stops computing once both position delta and velocity fall below `restDelta` / `restSpeed`. - **Velocity handoff:** Mid-animation retargets carry velocity into the new spring, so rapid input doesn't produce visual jumps. - **SSR-safe:** Returns a static motion value with no-op `.set` / `.jump` on the server. ## Common patterns ### Pointer tracking ```svelte { x.set(e.clientX); y.set(e.clientY) }} />

Cursor follower

``` ### Toggle animation ```svelte ``` ### With useVelocity Track the velocity of a spring for momentum-based effects: ```svelte

Momentum skew

``` > `useVelocity` and `useTransform` still return Svelte stores in this release (`$skew`). They'll migrate to motion values in a future release; the `.current` pattern will apply there too. ## API Reference ### Signature ```ts useSpring( source: number | string | MotionValue | Readable, options?: UseSpringOptions ): SpringMotionValue ``` ### Parameters - **source** — Initial value, unit string, another `MotionValue` to follow, or a Svelte readable store to follow. - **options** — `SpringOptions` plus `skipInitialAnimation`. See [Configuration](#configuration). ### Returns A `SpringMotionValue` — a real motion-dom `MotionValue` augmented with: - **`current`** `T` (getter) — Svelte 5 reactive read backed by `$state`. - **`set(value)`** — animate toward a new target. - **`jump(value)`** — set immediately, no animation. - **`get()`** — imperative current-value read. - **`on(event, cb)`** — subscribe to `'change'` / `'animationStart'` / `'animationComplete'` / `'animationCancel'` / `'destroy'`. - **`subscribe(run)`** — Svelte readable store contract for `$store` syntax and store-consumers. - **`destroy()`** — early teardown. - All other `MotionValue` methods from motion-dom (`getVelocity`, etc.). ## When to use - **Smooth value transitions** — animate any numeric value with natural-feeling motion. - **Pointer following** — track cursor or touch position with spring physics. - **Interactive toggles** — smoothly animate between states on user interaction. - **Smoothing scroll progress** — wrap `useScroll`'s output for buttery progress bars and parallax. For gesture-driven springs, combine with event handlers. For time-based animations, see [useTime](/docs/use-time) + [useTransform](/docs/use-transform). ## See also - [useVelocity](/docs/use-velocity) — track the velocity of a spring or any motion value. - [useTransform](/docs/use-transform) — map spring values to other ranges. - [useMotionTemplate](/docs/use-motion-template) — compose CSS strings from spring values. - [useTime](/docs/use-time) — reactive time source for continuous animations. --- Based on [Motion's useSpring](https://motion.dev/docs/react-use-spring) API; physics delegated to motion-dom's `attachFollow`.