https://github.com/bmcmahen/react-gesture-responder
a gesture responder system for your react application
https://github.com/bmcmahen/react-gesture-responder
gesture hooks react touch
Last synced: 6 months ago
JSON representation
a gesture responder system for your react application
- Host: GitHub
- URL: https://github.com/bmcmahen/react-gesture-responder
- Owner: bmcmahen
- Created: 2019-05-01T17:31:30.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-09T21:50:10.000Z (almost 3 years ago)
- Last Synced: 2025-04-04T19:56:19.634Z (6 months ago)
- Topics: gesture, hooks, react, touch
- Language: TypeScript
- Homepage: http://react-gesture-responder.netlify.com
- Size: 4.03 MB
- Stars: 115
- Watchers: 2
- Forks: 15
- Open Issues: 30
-
Metadata Files:
- Readme: Readme.md
Awesome Lists containing this project
README
# react-gesture-responder
[](https://www.npmjs.com/package/react-gesture-responder)
[](https://twitter.com/intent/follow?screen_name=benmcmahen)
`react-gesture-responder` offers a gesture responder system for your react application. It's heavily inspired by [react-native's](https://facebook.github.io/react-native/docs/gesture-responder-system.html) pan-responder. It's built for use in [Sancho-UI](https://github.com/bmcmahen/sancho).
[View the demo and website here](http://react-gesture-responder.netlify.com/).
You can also read how to [create a swipe to like feature](https://benmcmahen.com/building-react-components-with-gesture-support/) using react-gesture-responder.
## Features
- **The ability to delegate between multiple overlapping gestures.** This means that you can embed gesture responding views within eachother and provide negotiation strategies between them.
- **Simple kinematics for gesture based animations.** Values including distance, velocity, delta, and direction are provided through gesture callbacks.
- **Integrates well with [react-spring](react-spring.io) to create performant animations**.
- **Built with react-gesture-responder:** [react-gesture-view](https://github.com/bmcmahen/react-gesture-view), [touchable-hook](https://github.com/bmcmahen/touchable-hook), [react-grid-dnd](https://github.com/bmcmahen/react-grid-dnd), [react-gesture-gallery](https://github.com/bmcmahen/react-gesture-gallery), [react-gesture-stack](https://github.com/bmcmahen/react-gesture-stack), [sancho-ui](https://github.com/bmcmahen/sancho).
## Getting started
Install into your react project using yarn or npm.
```
yarn add react-gesture-responder
```
The example below demonstrates how it can be used in conjunction with `react-spring`.
```jsx
import { useSpring, animated } from "react-spring";
import { useGestureResponder } from "react-gesture-responder";
function Draggable() {
const [{ xy }, set] = useSpring(() => ({
xy: [0, 0]
}));
const { bind } = useGestureResponder({
onStartShouldSet: () => true,
onRelease: onEnd,
onTerminate: onEnd,
onMove: ({ delta }) => {
set({
xy: delta,
immediate: true
});
}
});
function onEnd() {
set({ xy: [0, 0], immediate: false });
}
return (
`translate3d(${x}px, ${y}px, 0)`)
}}
{...bind}
/>
);
}
```
## API
Only one responder can be active at any given time. The `useGesture` hook provides callbacks which allow you to implement a negotiation strategy between competing views.
- `onStartShouldSet: (state, e) => boolean` - Should the view become the responder upon first touch?
- `onMoveShouldSet: (state, e) => boolean` - This is called during any gesture movement on the view. You can return true to claim the responder for that view.
- `onStartShouldSetCapture: (state, e) => boolean` - The same as above, but using event capturing instead of bubbling. Useful if you want a parent view to capture the responder prior to children.
- `onMoveShouldSetCapture: (state, e) => boolean`.
- `onTerminationRequest: (state) => boolean`. - Should we allow the responder to be claimed by another view? This is only called when a parent `onMoveShouldSet` returns true. By default, it returns true.
By default, if a parent and child both return true from `onStartShouldSet` the child element will claim the responder.
Once a responder is claimed, other callbacks can be used to provide visual feedback to the user.
- `onGrant: (state, e) => void` - called when the view claims the responder, typically corresponding with `mousedown` or `touchstart` events.
- `onMove: (state, e) => void`
- `onRelease: (state, e) => void` - corresponds with `mouseup` or `touchend` events.
- `onTerminate: (state) => void` - called when the responder is claimed by another view.
```js
const { bind } = useGestureResponder(
{
onStartShouldSet: state => true,
onStartShouldSetCapture: state => false,
onMoveShouldSet: state => false,
onMoveShouldSetCapture: state => false,
onTerminationRequest: state => true,
onGrant: state => {},
onRelease: state => {},
onTerminate: state => {},
onMove: state => {}
},
{
uid: "a-unique-id",
enableMouse: true
}
);
```
`state` contains the following values:
```js
export interface StateType {
time: number;
xy: [number, number];
delta: [number, number];
initial: [number, number];
previous: [number, number];
direction: [number, number];
initialDirection: [number, number];
local: [number, number];
lastLocal: [number, number];
velocity: number;
distance: number;
}
```
## Prior art
- [react-native-web](https://github.com/necolas/react-native-web/blob/master/packages/react-native-web/src/vendor/react-native/PanResponder/index.js)
- [react-with-gesture](https://github.com/react-spring/react-use-gesture) for some of the kinematics.
## License
MIT