Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pocket-stack/pocketjs/llms.txt

Use this file to discover all available pages before exploring further.

@pocketjs/framework/animation provides three functions for driving motion in PocketJS. All animation runs at a fixed dt = 1/60 s inside the Rust core — JS declares the tween once and the native renderer ticks it per vblank without any further JS involvement, making tweens byte-exact and zero-cost once started. Prop names are spec PROP keys; only animatable props are accepted. Non-animatable props throw at call time. 
import { animate, spring, cancelAnim } from '@pocketjs/framework/animation';
import type { AnimateOptions, EasingName } from '@pocketjs/framework/animation';

​
animate

Tweens a node prop from its current value to to. Returns an animId that can be passed to cancelAnim to stop the tween early. For color props, to accepts either a packed u32 ABGR value or a CSS hex string in '#rrggbb' or '#rrggbbaa' format. 
function animate(
  node: NodeMirror | number,
  prop: PropName,
  to: number | string,
  opts?: AnimateOptions,
): number
​
node
NodeMirror | number
required
The target node. Pass a NodeMirror from a ref callback, or a raw node id. Using a NodeMirror is preferred — it is type-safe and self-documenting.
​
prop
PropName
required
The spec prop to animate. Must be an animatable prop — see the animatable props list below. Throws on an unknown or non-animatable prop.
​
to
number | string
required
Target value. For numeric props, pass a number. For color props (color, bgColor, etc.) pass a packed u32 ABGR or a hex string ('#rrggbb', '#rrggbbaa'). The tween starts from the node’s current value at call time.
​
opts
AnimateOptions
Duration, easing, and delay. All fields are optional with sensible defaults.
Returns: number — an animId for cancelAnim.

​
spring

Springs a node prop to to using physics-based motion. Duration is determined by the physics simulation, not a fixed timer. Accepts an optional preset to select the spring character. Returns an animId. 
function spring(
  node: NodeMirror | number,
  prop: PropName,
  to: number | string,
  preset?: "default" | "bouncy",
): number
​
node
NodeMirror | number
required
The target node. Pass a NodeMirror or a raw node id.
​
prop
PropName
required
The spec prop to spring. Must be animatable. Throws on unknown or non-animatable props.
​
to
number | string
required
Target value. Same encoding rules as animate — number or '#rrggbb' hex string for color props.
​
preset
"default" | "bouncy"
Spring character. "default" is a smooth, well-damped spring. "bouncy" is more elastic with more oscillation. Defaults to "default".
Returns: number — an animId for cancelAnim.

​
cancelAnim

Stops a running animation immediately, leaving the property at whatever value the tween had reached. 
function cancelAnim(animId: number): void
​
animId
number
required
The id returned by animate or spring. Calling with a stale or already-cancelled id is a no-op.

​
AnimateOptions

All fields are optional. Pass only the fields you need — the rest take their defaults.
FieldTypeDefaultDescription
durnumber200Duration in ms. Ignored by spring easings ("spring", "spring-bouncy") — physics determines the duration instead.
easingEasingName | number"out"Named easing curve or a raw ENUMS.Easing ordinal. Named values are preferred.
delaynumber0Delay in ms before the tween starts. The property holds its current value during the delay.

​
EasingName

The named easing curves available for animate and via AnimateOptions.easing.
ValueFeel
'linear'Constant speed from start to end.
'in'Ease-in — starts slow, accelerates toward the target.
'out'Ease-out — decelerates into the target. Default.
'in-out'Ease-in-out — slow at both ends, fastest in the middle.
'out-back'Overshoots the target briefly, then settles back. Good for pop-in effects.
'spring'Physics spring — duration comes from the simulation, dur is ignored. Smoothly damped.
'spring-bouncy'Springier physics spring with more oscillation. dur is ignored.

​
Animatable props

Only spec PROP keys marked animatable are accepted. Passing a non-animatable prop throws immediately. The most commonly animated props are:
PropDescription
translateXHorizontal offset in px (paint-only, no relayout).
translateYVertical offset in px (paint-only, no relayout).
scaleUniform scale factor (paint-only).
rotateRotation in degrees (paint-only).
opacityAlpha from 0.0 (invisible) to 1.0 (opaque).
color propsAny color prop accepts a packed u32 ABGR or '#rrggbb' string. Color channels are interpolated independently per vblank.

​
Usage example

Use a ref callback to capture the NodeMirror, then call animate in response to a state change or button press. 
import { animate } from '@pocketjs/framework/animation';
import type { NodeMirror } from '@pocketjs/framework';

let panel: NodeMirror | undefined;

function MyPanel() {
  return (
    <View
      ref={(node) => { panel = node; }}
      class="absolute inset-0 flex-col items-center justify-end"
    />
  );
}

// Slide the panel up 32 px with an overshoot
function showPanel() {
  if (panel) {
    animate(panel, 'translateY', -32, { dur: 200, easing: 'out-back' });
  }
}

// Fade it back and return to origin
function hidePanel() {
  if (panel) {
    animate(panel, 'translateY', 0, { dur: 150, easing: 'out' });
    animate(panel, 'opacity', 0, { dur: 150, easing: 'out' });
  }
}
Calling animate a second time on the same prop before the first tween finishes cancels the in-flight tween and starts a new one from the current value — no need to call cancelAnim manually in most cases. 
// Spring a card to a new position on trigger press
import { spring } from '@pocketjs/framework/animation';

let card: NodeMirror | undefined;

function onTrigger() {
  if (card) {
    spring(card, 'translateX', 120, 'bouncy');
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us