@damped/core

@damped/core is the framework-agnostic package. It has no dependencies, never imports React, and importing it is safe on a server: nothing touches window, document, requestAnimationFrame, matchMedia or getComputedStyle until you call an API that needs them.

bun

bun add @damped/core

npm

npm install @damped/core

Not published yet

The packages have not been published to npm at the time of writing. The commands above are what you will run once they are; until then, use the workspace packages from the repository.

The package is sideEffects: false and tree-shakable. An application that only calls animate bundles about 3.95 KB gzip; the whole package is about 6.99 KB gzip. The compositor driver is a value you import, so it is left out of bundles that never use it.

All exports

The package exports 13 values and 23 types. Every entry below has its own anchor on the page it links to.

Export	Kind	Page
springParams	function	Springs
createSpring	function	Springs
SpringOptions, SpringParams, SpringState, Spring	types	Springs
createScheduler, frame	functions	Scheduler
FrameInfo, FrameSource, Phase, FrameJob, Scheduler	types	Scheduler
createSpringValue	function	Spring values
SpringValue, SpringValueOptions	types	Spring values
animate	function	animate
AnimatableProperty, AnimationTargets, AnimateOptions, AnimationControls	types	animate
compositor	value	Compositor
Driver	type	Compositor
layout, snapshot, measureLayout	functions	Layout
Box, LayoutOptions, LayoutSnapshot	types	Layout
morph	function	Morph
MorphOptions, MorphControls	types	Morph
enter, exit	functions	Presence
EnterOptions, ExitOptions	types	Presence

Anything not in this list is internal and not reachable from the package entry.

Conventions shared by every API

Reading the signatures

Signature blocks are declarations excerpted from the source. They have no bodies, so they are marked nocheck and are not compiled. Every other ts and tsx block in this reference is a complete example that is typechecked against the real packages by the docs test suite.

Two ways to describe a spring

Every API that takes a spring accepts SpringOptions in one of two forms:

• Perceptual: duration and bounce. This is the form to reach for first. duration is the period of the undamped oscillation in seconds, not the time to rest.
• Physical: stiffness, damping and mass. The physical form is selected by the presence of a stiffness key; damping is then required.

Defaults are duration: 0.5, bounce: 0.15, mass: 1, restDelta: 0.001 and restSpeed: 0.01. animate replaces the two rest thresholds per property with values suited to pixels and ratios.

Invalid options throw a RangeError with the message <name> must be <requirement>, received <value>, before any element is touched or any frame is requested.

Time and units

The frame source timestamp is in milliseconds. Springs take and report seconds, and velocities are in units per second. A spring is evaluated in closed form, so the state at a given time does not depend on the frame rate or on which times were asked before.

Interruption

Retargeting a moving spring keeps its position and velocity. Every element API (animate, layout, morph, enter, exit, the React hooks) hands a running animation to the next one instead of restarting it. See Interruption and reversal.

Reduced motion

The element APIs follow prefers-reduced-motion through the reducedMotion option: spatial properties (x, y, rotate, scale, scaleX, scaleY) jump to their target, and opacity and blur still animate. Plain numbers (createSpring, createSpringValue) are never affected; decide for yourself, for instance by calling jump. See Reduced motion.

Server rendering

Importing any package entry is safe without a DOM. Element APIs need an Element, so they run on the client only.

Errors thrown by your callbacks

A scheduler job, a SpringValue listener or an exit remove callback that throws never breaks the frame, the value or a promise. The error is rethrown from a microtask so it still reaches your error reporting.

Elements have one scheduler

The first animate, layout, morph, enter or exit call on an element fixes the scheduler that drives it. Later calls with a different scheduler option on the same element are driven by the first one. In tests, use a fresh element per scheduler. See Testing.

See also: Springs explained, Interruption and reversal, React reference, React Native reference, Demos.