@use-gesture Documentation

The structure of your configuration object depends on whether you are using gesture-specific hooks, the general useGesture hook, or the Vanilla JavaScript classes (DragGesture or Gesture).

• Gesture-specific hooks: Pass shared options and gesture-specific options in a single object.
• useGesture hook: Pass an object containing event handlers (e.g., onDrag, onPinch) as the first argument, and a second object containing shared options and gesture-specific configuration objects (e.g., drag: { ... }).
• Vanilla Classes:
  • DragGesture: Pass the element, handler, and a single config object containing shared and drag-specific options.
  • Gesture: Pass the element, an object of handlers, and a second object containing shared and gesture-specific configuration objects.

// when you use a gesture-specific hook
useDrag((state) => doSomethingWith(state), { ...sharedOptions, ...dragOptions })

// when you use the useGesture hook
useGesture(
  {
    onDrag: (state) => doSomethingWith(state),
    onPinch: (state) => doSomethingWith(state)
    // ...
  },
  {
    // global options such as `target`
    ...sharedOptions,
    // gesture specific options
    drag: dragOptions,
    wheel: wheelOptions,
    pinch: pinchOptions,
    scroll: scrollOptions,
    hover: hoverOptions
  }
)

// when you use a gesture-specific class
new DragGesture(
  element,
  state => doSomethingWith(state),
  { ...sharedOptions, ...dragOptions }
)

// when you use the Gesture class
new Gesture(element, {
  onDrag: state => doSomethingWith(state),
  onPinch: state => doSomethingWith(state),
  // ...
  {
    // global options such as `target`
    ...sharedOptions,
    // gesture specific options
    drag: dragOptions,
    wheel: wheelOptions,
    pinch: pinchOptions,
    scroll: scrollOptions,
    wheel: wheelOptions,
    hover: hoverOptions,
  }
})

When implementing horizontal gestures (like swiping an item to reveal actions) on mobile, you often want to prevent the page from scrolling vertically while the user is interacting with the element.

Instead of calling event.preventDefault(), use the CSS touch-action property on the element being dragged.

• Use touch-action: pan-y to allow only vertical scrolling while the element is being interacted with. This allows the browser to natively handle vertical scrolling while your gesture handler manages horizontal movement.
• Use touch-action: none if you want to disable all browser-native touch interactions (both vertical and horizontal) on that element.

Important: When using touch-action: pan-y for horizontal gestures, you should also set the { axis: 'x' } option in your gesture handler to ensure the handler only responds to movement on that specific axis.

function TouchActionExample() {
  const [springs, api] = useSprings(4, () => ({ x: 0 }))

  const bind = useDrag(
    ({ down, movement: [x], args: [index] }) => api.start((i) => i === index && { x: down ? x : 0 }),
    {
      axis: 'x'
    }
  )

  return springs.map(({ x }, i) => <animated.div {...bind(i)} style={{ x, touchAction: 'pan-y' }} />)
}

In React, @use-gesture provides hooks like useDrag that you can attach to components. The hook returns a bind function; when called and spread onto a component (e.g., <div {...bind()} />), it attaches necessary pointer event handlers like onPointerDown, onPointerMove, and onPointerUp.

Note: @use-gesture provides the gesture data, but it is not responsible for the actual movement/animation. You should combine it with an animation library like react-spring to handle component transforms.

import { useSpring, animated } from '@react-spring/web'
import { useDrag } from '@use-gesture/react'

function PullRelease() {
  const [{ x, y }, api] = useSpring(() => ({ x: 0, y: 0 }))

  // Set the drag hook and define component movement based on gesture data
  const bind = useDrag(({ down, movement: [mx, my] }) => {
    api.start({ x: down ? mx : 0, y: down ? my : 0, immediate: down })
  })

  // Bind it to a component
  return <animated.div {...bind()} style={{ x, y }} />
}