#@lynx-js/motion

@lynx-js/motion is a thin adaptation layer that reuses Motion's source directly to bring its imperative JavaScript APIs to Lynx. All APIs run in the main-thread script environment, so animations update visual properties immediately without round-tripping through the background thread. If you know Motion's animate(), motionValue(), and spring on the web, you already know how to use them in Lynx. If you are new to Motion, the Motion quick-start guide covers the fundamentals.

#Install

npm install @lynx-js/motion

yarn add @lynx-js/motion

pnpm add @lynx-js/motion

bun add @lynx-js/motion

deno add npm:@lynx-js/motion

Import from the main package entry:

import { animate, motionValue, styleEffect } from '@lynx-js/motion';

#Animate an element ref

The animate() function accepts the same options as Motion on the web, including duration, ease, delay, repeat, and type: 'spring'. See the Motion animate() reference for the full option list.

The usual pattern is:

1. Create a main-thread element ref with useMainThreadRef().
2. Attach it to the element with main-thread:ref.
3. Start animate() inside a main-thread function.
4. Store the animation controls in another main-thread ref so cleanup can call stop().

#Use Springs

Set type: 'spring' when a value should settle with spring physics instead of following a fixed-duration easing curve. All spring options from Motion are supported, including stiffness, damping, mass, and bounce.

#Use Motion Values

motionValue() stores a value, can be animated directly with animate(), and lets you subscribe to changes. Use it when multiple effects or event handlers need a shared animated value.

#Build Gesture Effects

For high-frequency touch input, keep the event handlers on the main thread with main-thread:bindtouchstart, main-thread:bindtouchmove, and main-thread:bindtouchend. Use motion values with styleEffect() to derive visual state from gesture state.