Gesture-Driven Animations with use-gesture

@use-gesture/react is a gesture recognition library designed to work seamlessly with react-spring. It recognizes drag, pinch, scroll, hover, move, and wheel gestures, providing normalized gesture state that you pipe directly into spring setters for fluid, physics-based interactions.

The useDrag hook fires a callback on every drag event. The callback receives a gesture state object with key properties: movement (total displacement from drag start), velocity (current speed), direction (1 or -1 per axis), first (true on drag start), last (true on drag end), and event (the raw DOM event).

All use-gesture hooks return a bind() function. Calling bind() returns an object of event handler props (onPointerDown, onTouchStart, etc.) that you spread onto the element you want to make interactive. This is the connection point between the gesture recognizer and your DOM element.

The standard pattern: create a spring with the imperative API ([springs, api] = useSpring(...)), then use useDrag to call api.start({ x: movement[0], y: movement[1] }) on each drag event. The spring smoothly follows the drag movement, adding natural physics to what would otherwise be rigid cursor tracking.

When a drag ends (last: true in gesture state), you typically snap the element back to its origin. Call api.start({ x: 0, y: 0 }) inside an if (last) check. react-spring animates back with spring physics — a gentle bounce rather than an instant reset — giving the interaction a satisfying physical feel.

The velocity value in gesture state enables throw behavior. When the user releases with high velocity, you can fling the element in the drag direction instead of snapping back. Check if (last && velocity[0] > threshold) then animate the element to its final off-screen position. This is essential for swipe-to-dismiss interactions.

To restrict drag movement within a container, clamp the movement values before passing them to the spring: x: Math.max(-maxX, Math.min(maxX, movement[0])). Alternatively, use use-gesture's built-in bounds option: useDrag(handler, { bounds: { left: -100, right: 100 } }) to automatically clamp gesture state.

A mobile swipe-to-dismiss implementation: use useDrag to track horizontal movement. If the user releases with velocity above a threshold OR has moved more than half the screen width, animate the card off-screen (api.start({ x: window.innerWidth })) and then remove it from the list. Otherwise, snap it back to center.

usePinch recognizes two-finger pinch gestures on touch screens and Ctrl+wheel on desktop. The gesture state includes scale (current zoom level relative to pinch start) and origin (center point of the pinch). Connect to a spring tracking scale to create smooth, bounded zoom interactions on images or maps.

useHover fires when the pointer enters or leaves an element, providing an active boolean. useMove tracks mouse position within an element, providing normalized coordinates. Both are useful for magnetic hover effects where elements subtly shift toward the cursor as it approaches.

use-gesture hooks compose together. You can use both useDrag and usePinch on the same element: const bindDrag = useDrag(...); const bindPinch = usePinch(...), then spread both bind functions: ...bindDrag() ...bindPinch(). use-gesture handles the disambiguation between gesture types automatically.

What does the bind() function returned by use-gesture hooks do?

@use-gesture/react provides useDrag, usePinch, useScroll, useHover, and useMove. Each hook returns a bind() function whose spread result wires gesture events to DOM elements. Gesture state provides movement, velocity, direction, first, and last. Combine with react-spring's imperative api.start() for physics-based interactive animations. Use velocity for fling/dismiss and bounds for movement clamping.