React animations - EXPRESSO Docs

Use style.transition for ordinary style changes caused by React state when no native gesture lifecycle is involved. Do not use it as the pressed or selected interaction contract. Wrap interactive content in gestureDetector and use shared values when feedback is gesture-driven, interruptible, or needs to be cancelled or awaited.

Simple transitions

Use a transition when React state changes a style value and no imperative animation control is needed.

export function StatusBanner({ visible }: { visible: boolean }) {
  return (
    <box
      style={{
        alpha: visible ? 1 : 0,
        transition: "alpha 180ms ease-out"
      }}
    >
      <text>Changes saved</text>
    </box>
  );
}

This is appropriate for a regular state-driven visibility change. For pressed or selected feedback, use gestureDetector and shared values so the visual state follows the native gesture lifecycle.

Shared values

Use sv or sharedValue for a mutable value that updates outside normal React render flow.

import { useEffect } from "react";
import { animatedProps, sv } from "@napps/nodes";

export function LoadingIndicator() {
  const opacity = sv(0.4);

  useEffect(() => {
    opacity.value = 1;
  }, []);

  return <box style={animatedProps({ alpha: opacity })} />;
}

Always read and write .value. Assigning a number or color updates immediately; assigning an animation handle starts an animation.

Timing animation

timing moves a value to a target over a duration using an easing curve.

import { useEffect } from "react";
import { animatedProps, sv, timing } from "@napps/nodes";

export function SlideIn() {
  const x = sv(-120);

  useEffect(() => {
    x.value = timing(0, { duration: 300, easing: "quadOut" });
  }, []);

  return <box style={animatedProps({ translationX: x })} />;
}

Spring animation

spring is useful for physical movement and settling after a gesture.

import { useState } from "react";
import { animatedProps, spring, sv } from "@napps/nodes";

export function SpringPanel() {
  const [open, setOpen] = useState(false);
  const height = sv(0);

  function toggle() {
    setOpen((value) => !value);
    height.value = spring(open ? 0 : 240, {
      response: 0.35,
      dampingFraction: 0.8
    });
  }

  return (
    <touchable onPress={toggle}>
      <box style={animatedProps({ height })}>
        <text>{open ? "Close" : "Open"}</text>
      </box>
    </touchable>
  );
}

Decay animation

withDecay continues movement from an initial velocity and can stop at bounds.

import { animatedProps, sv, withDecay } from "@napps/nodes";

export function MomentumCard() {
  const offset = sv(0);

  return (
    <gestureDetector
      gesture="pan"
      onEnd={(event) => {
        offset.value = withDecay({
          velocity: event.velocityX,
          deceleration: 0.998,
          clamp: [-240, 240]
        });
      }}
    >
      <box style={animatedProps({ translationX: offset })}>
        <text>Release to coast</text>
      </box>
    </gestureDetector>
  );
}

Delay, sequence, and repeat

Use composition helpers when multiple animations form one behavior.

import { useEffect } from "react";
import {
  animatedProps,
  delayed,
  repeat,
  sequence,
  sv,
  timing,
  withDelay,
  withRepeat,
  withSequence
} from "@napps/nodes";

export function AttentionPulse() {
  const alpha = sv(1);

  useEffect(() => {
    alpha.value = withSequence(
      withDelay(150, timing(0.45, { duration: 120 })),
      withRepeat(timing(1, { duration: 250 }), 3, true)
    );
  }, []);

  // Factory helpers are useful when the same behavior must be awaited or reused:
  const pulse = sequence(
    delayed(150, (callback) => timing(0.45, { duration: 120 }, callback)),
    repeat((callback) => timing(1, { duration: 250 }, callback), 3, true)
  );
  void pulse;

  return <box style={animatedProps({ alpha })} />;
}

withRepeat repeats an animation directly. repeat creates a reusable factory. Create fresh handles for each run.

Keyframes

Use keyframes for multiple stops with different values or easing per segment.

import { useEffect } from "react";
import { animatedProps, keyframes, sv } from "@napps/nodes";

export function ProgressSweep() {
  const progress = sv(0);

  useEffect(() => {
    progress.value = keyframes(
      [
        { offset: 0, value: 0 },
        { offset: 0.25, value: 100, easing: "quadOut" },
        { offset: 1, value: 50, easing: "linear" }
      ],
      { duration: 800 }
    );
  }, []);

  return <box style={animatedProps({ translationX: progress })} />;
}

Derived values

Derived values update automatically from other reactive values and cannot be assigned directly.

import { useEffect } from "react";
import { animatedProps, clamp, interpolate, sv } from "@napps/nodes";

export function ScrollHeader() {
  const scrollY = sv(0);
  const headerAlpha = interpolate(scrollY, [0, 120], [1, 0]);
  const headerOffset = clamp(scrollY, 0, 64);

  useEffect(() => {
    scrollY.value = 80;
  }, []);

  return (
    <box
      style={animatedProps({
        alpha: headerAlpha,
        translationY: headerOffset
      })}
    >
      <text>Header</text>
    </box>
  );
}

add and multiply combine reactive values into another derived value.

Gesture-driven animation

Use mapEvent for high-frequency event fields and settle the value with spring when the gesture ends.

import { animatedProps, mapEvent, spring, sv } from "@napps/nodes";

export function DraggableCard() {
  const x = sv(0);

  return (
    <gestureDetector
      gesture={{ type: "pan", minDistance: 8 }}
      onUpdate={mapEvent({ translationX: x })}
      onEnd={(event) => {
        x.value = spring(0, { velocity: event.velocityX });
      }}
    >
      <box style={animatedProps({ translationX: x })}>
        <text>Drag me</text>
      </box>
    </gestureDetector>
  );
}

Awaiting and cancelling

Use promise helpers when the next action depends on completion.

import { useEffect } from "react";
import {
  runAnimation,
  runAnimationOrThrow,
  runParallel,
  sv,
  toSpring,
  toTiming
} from "@napps/nodes";

export function CoordinatedAnimation() {
  const x = sv(0);
  const opacity = sv(0);

  useEffect(() => {
    let cancelled = false;

    async function run() {
      await runAnimation(x, toSpring(100));
      if (cancelled) return;

      await runParallel([
        { value: x, animation: toTiming(0, { duration: 250 }) },
        { value: opacity, animation: toTiming(1, { duration: 250 }) }
      ]);

      await runAnimationOrThrow(opacity, toTiming(0, { duration: 250 }));
    }

    void run();
    return () => {
      cancelled = true;
    };
  }, []);

  return <text>Animation sequence</text>;
}

runAnimation resolves with an AnimationResult. runAnimationOrThrow rejects with AnimationCompletionError when the animation does not finish naturally. Use cancelAnimation(value) when you need to stop an active animation explicitly.

Completion reasons

Callbacks and promise helpers report:

completed: reached the target naturally.
cancelled: stopped with cancelAnimation.
replaced: another animation took over the same value.
overwritten: a direct .value assignment replaced the animation.

Best practices

Prefer style.transition for ordinary state-driven visual changes, not pressed or selected feedback that depends on a native gesture lifecycle.
Use mapEvent for high-frequency gesture and scroll updates.
Create fresh animation handles; do not reuse them in multiple compositions.
Cancel or invalidate async animation flows when the component unmounts.
Animate only fields supported by animatedProps.

​Simple transitions

​Shared values

​Timing animation

​Spring animation

​Decay animation

​Delay, sequence, and repeat

​Keyframes

​Derived values

​Gesture-driven animation

​Awaiting and cancelling

​Completion reasons

​Best practices