withDecay

withDecay simulates momentum with friction. A value keeps moving and gradually slows to a stop, rather than animating to a fixed target. Built for the tail end of gestures (flicks, swipes, momentum scrolling).

Signature

function withDecay(
  velocity: number,
  options?: {
    clamp?: [number, number]; // hard-stop bounds
    elastic?: boolean | number; // rubber-band past clamp; true = default constant
    onStart?: () => void;
    onChange?: (value: number) => void;
    onComplete?: () => void;
  }
): Descriptor;

Usage

import { useValue, withDecay, animate } from 'react-ui-animate';

function Flingable() {
  const [x, setX] = useValue(0);

  return (
    <animate.div
      style={{ translateX: x }}
      onClick={() =>
        /* Momentum from velocity — slows to a stop inside clamp */
        setX(withDecay(0.8, { clamp: [-200, 200] }))
      }
    />
  );
}

Preview

useDrag's momentum/bounds/elastic options already wire this up for dragging. Reach for withDecay directly when you need momentum from something other than a drag gesture (e.g. a button-triggered flick, or a custom Gesture.Scroll()/Gesture.Wheel() velocity).

Next steps

• useDrag: momentum built in for drag gestures.
• useGesture: raw velocity from Gesture.Scroll()/Gesture.Wheel().
• withSpring: for a fixed-destination alternative.