JavaScript API

Every animating component exposes a Web-Animations-style playback surface: play(), pause(), finish(), cancel(), a playState getter, and a finished promise — plus package-level helpers to control everything at once.

Controlling playback

motion-components

playState: –

Triggering a one-shot and awaiting it

Triggered from JavaScript

–

Controlling everything at once

The package exports registry-backed helpers that operate on every live instance, or only those inside a container you pass. Input-driven components (motion-hover, motion-press, motion-magnetic, motion-tilt) have no timeline; pauseAll() disables them and resumeAll() re-enables only the ones it disabled.

typing along…

Instance members

Member	Type	Default	Description
play()	() => Promise<void>	—	Start if idle or finished, resume if paused, no-op if running
pause()	() => void	—	Freeze in place; resumable with play()
finish()	() => void	—	Jump to the end state immediately
cancel()	() => void	—	Hard terminate and reset to the initial state
playState	PlaybackState	'idle'	'idle' \| 'running' \| 'paused' \| 'finished'
finished	Promise<void>	—	Fresh per run; resolves on finish or cancel, never rejects

Package exports

Export	Type	Default	Description
pauseAll(root?)	(root?: Node) => void	document	Pause running instances inside root; disable input-reactive components
resumeAll(root?)	(root?: Node) => void	document	Resume paused instances; re-enable only what pauseAll disabled
cancelAll(root?)	(root?: Node) => void	document	Cancel every instance inside root
MotionControllable	interface	—	TypeScript type for controllable element refs
PlaybackState	type	—	The four-state playback union

Scroll-driven components

For motion-parallax, motion-scene, motion-progress, and motion-blur the verbs adapt: pause() unbinds the scroll listener and freezes the effect at its current progress, play() rebinds, finish() applies the end-of-scroll state, and cancel() unbinds and resets styles. While bound, playState is 'running'.

Accessibility

The API always respects prefers-reduced-motion: a programmatic play() applies the final state instantly, still resolves finished, and still fires motion-start and motion-finish — so calling code never needs a reduced-motion branch.