use-gesture — Component-Tied Gesture Handling for React and Vanilla JS

Introduction

use-gesture is a gesture library from the Poimandres collective (pmndrs) that binds rich pointer and touch interactions to components. It provides hooks for drag, pinch, scroll, wheel, move, and hover gestures, with built-in velocity tracking and configurable bounds, making interactive UIs straightforward to build.

What use-gesture Does

• Provides React hooks for drag, pinch, scroll, wheel, move, and hover gestures
• Tracks velocity, direction, distance, and offset for each gesture
• Supports configurable bounds, thresholds, and axis locking
• Works with any animation library (react-spring, framer-motion, CSS)
• Offers a vanilla JS package for non-React projects

Architecture Overview

Each gesture hook registers pointer and touch event listeners on the target element. The library normalizes events across mouse, touch, and pointer APIs into a unified gesture state. On every event, it computes kinematic values (velocity, distance, direction) and calls your handler with the enriched state object. The library does not manage rendering; it only provides gesture data for your animation solution to consume.

Self-Hosting & Configuration

• Install for React: npm install @use-gesture/react
• Install for vanilla JS: npm install @use-gesture/vanilla
• Use individual hooks (useDrag, usePinch) or useGesture for multiple gestures
• Configure bounds: useDrag({ bounds: { left: -100, right: 100 } })
• Set axis constraints: useDrag({ axis: "x" }) for horizontal-only dragging

Key Features

• Unified gesture state with velocity and direction tracking
• Built-in rubberbanding, swipe detection, and momentum
• Works with any animation library or raw CSS transforms
• Touch and pointer event normalization across devices
• TypeScript support with strongly typed gesture state

Comparison with Similar Tools

• react-dnd — Focused on drag-and-drop data transfer; use-gesture handles physics-based gestures
• Hammer.js — Legacy gesture library; use-gesture is React-first with modern hooks API
• Framer Motion (gestures) — Bundled with its animation engine; use-gesture is animation-agnostic
• interact.js — Broader interaction library; use-gesture is lighter and hook-oriented

FAQ

Q: Does use-gesture work without react-spring? A: Yes. The gesture handlers provide raw values you can apply to any animation library, CSS variables, or direct style manipulation.

Q: Can I use use-gesture on mobile devices? A: Yes. It normalizes touch and pointer events and supports multi-touch gestures like pinch-to-zoom on mobile browsers.

Q: How do I combine multiple gestures on one element? A: Use the useGesture hook, which accepts handlers for multiple gesture types in a single call: useGesture({ onDrag: ..., onPinch: ... }).

Q: Is there a vanilla JavaScript version? A: Yes. The @use-gesture/vanilla package provides the same gesture engine without React dependencies.

Sources

• GitHub Repository
• Official Documentation