website·Indexed 29 days ago
https://use-gesture.netlify.app/A library for binding mouse and touch events to any node, making complex gestures such as drag, pinch, move, wheel, and scroll easy to configure. Available for both React and Vanilla JS, it provides a set of gesture handlers and utility functions to simplify mobile-friendly UI development.
@use-gesture is a library designed to simplify the configuration of complex gestures such as dragging and pinching. It provides a high-level API (e.g., onDrag) that is as easy to implement as native mouse events while maintaining full control over the gesture logic.
Key benefits include:
scroll, wheel, and move events.react-spring instead of React.useState. react-spring allows for animating components without triggering React render cycles.config object must now be passed as the second argument rather than inside the actions object.// OLD: [bind, props] = useGesture({ onAction: () => {}, config })
// NEW:
const bind = useGesture({ onDrag: () => { /* handler */ } }, { /* config options */ });event.preventDefault() within the gesture handler.img.drag {
touch-action: none;
-moz-user-select: none;
-webkit-user-drag: none;
user-select: none;
}useDrag(({ event, ...state }) => {
event.preventDefault()
// rest of your gesture logic
})cancel() function can be called within a handler to stop the current gesture. This is only supported for drag and pinch gestures.function CancelExample() {
const [{ x }, api] = useSpring(() => ({ x: 0 }))
const bind = useDrag(({ active, movement: [mx], cancel }) => {
if (mx > 200) cancel()
api.start({ x: active ? mx : 0, immediate: active })
})
return <animated.div {...bind()} style={{ x }} />
}
react-use-gesture package has been replaced by @use-gesture/react. While the API remains largely the same (approximately 95% compatibility), users must update their package imports and account for specific breaking changes in the configuration options.useGesture hook by passing only the specific actions you need to createUseGesture. The resulting hook accepts a configuration object with event handlers (e.g., onDrag, onDragStart, onDragEnd) and an optional config object for gesture-specific settings.import { createUseGesture, dragAction, pinchAction } from '@use-gesture/react'
// Create a custom hook with only drag and pinch support
const useGesture = createUseGesture([dragAction, pinchAction])
function MyComponent() {
const bind = useGesture(
{
onDrag: (state) => doSomethingWith(state),
onDragStart: (state) => doSomethingWith(state),
onDragEnd: (state) => doSomethingWith(state),
onPinch: (state) => doSomethingWith(state),
onPinchStart: (state) => doSomethingWith(state),
onPinchEnd: (state) => doSomethingWith(state)
},
{ drag: dragConfig, pinch: pinchConfig }
)
return <div {...bind()} />
}useGesture are now separated per gesture, and event options have been restructured. Specifically, dragDelay has been renamed to delay and moved inside the drag configuration object.// BEFORE (v6)
useGesture(fn, {
enabled: true,
event: { passive: true, capture: false },
pointerEvents: true,
wheel: false,
dragDelay: 100
})
// AFTER (v7)
useGesture(fn, {
enabled: true,
eventOptions: { passive: true, capture: false, pointer: true },
wheel: {
enabled: false
},
drag: {
delay: 100
}
})
// Alternatively, using the shorthand hook:
useDrag(fn, {
eventOptions: { passive: true, capture: false, pointer: true },
delay: 100
})@use-gesture/react package.import { useGesture } from '@use-gesture/react';Relative values are preferred for CSS transforms.
movement: The displacement of the current gesture. It resets to [0,0] every time a new gesture starts. Use this when an element should snap back to its original position after release.offset: The cumulative sum of all gesture movements on the same component. Use this when an element should stay where the user left it.// Example: Component stays where you left it using offset
function OffsetExample() {
const [{ x, y }, api] = useSpring(() => ({ x: 0, y: 0 }))
const bind = useDrag(({ offset: [x, y] }) => api.start({ x, y }))
return <animated.div {...bind()} style={{ x, y }} />
}
body should not scroll while the overlay is active, use the body-scroll-lock library. It is recommended to first check if the issue can be solved using the CSS touch-action property before introducing this library.