{"bugs":{"url":"https://github.com/react-spring/react-use-gesture/issues"},"dist":{"shasum":"8dca5abf2511b5c7467e4a56bbda3b62cf0c2818","tarball":"https://registry.npmjs.org/react-use-gesture/-/react-use-gesture-5.1.0.tgz","fileCount":34,"integrity":"sha512-13NJuPQ3xjvRA5sPYxjbctxF50ec3QaggHnKAJSPnq1DGygyysO8Q/cxxBku4hBnpRFRj1k9AkTIsgglie4oPg==","signatures":[{"sig":"MEUCIQDvGC1r/CiBEpGOwWjz2P2aMAhQV8UOyaIRL5Jm4Rs3GAIgChHUbinHphyTkjzZO9V0FpE6S2B89S7TkGl1ki/2fQE=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":368994,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc29MeCRA9TVsSAnZWagAAmckQAKGQAD9CKlIduYP74SCQ\ngfWachOxivKdH1B817cUW/Fc6gNNGVA+mzi10S+C01eqb01QRu90XXJ9xBHI\nXyDeRtOQcpf8nvUnZDegb5tIO+XIyzmcEGOt8LbQfYwfVeL+KB1hfIjNq+Cy\n8ezbmLvK8UYIL+/oIqp5Kbcp+k6tyLsEBVP5Us9C0+0i+uy9lfHpg/SVVeCB\nGio4n1+ji+0JPA5qK+yV1+o8HeVbdmq6ujSsn16WPa9Emi+LUhyS6KYZ5kPs\nfNQnzcDfS/zvIESFZBdEuocmcMf26k3XAGRAZoaHAnWsU2/hSjGbET0SIaa5\nG8YbgPMJZayNUfLQn8PxrzFNXvaDfcavFIasaWvaS/I/oNEV1WM12hCPvB22\n8Xx5LeZlXOlRShhfbO/AAN8UWPy2REoYPaFpNkYNnyAp6gbICc3ySN3eFJA2\n3Erbj+O6QQP/z6YnilrEuNVyIjIr3MWvfrUfiPs+YlPwQ2tMKaJcMc88Dsx+\nqL/9D/Zh7rZCqIY8gbeKoNS3DWQFiWjSkAyf1WeJXBoVnsK/qYCuT7jevs8K\nt4oGPmmoswIfvl3Y0fEUSK/pGmfVIB+wfqjAJGbMqXqnp8FhTyNaWDqTfMST\nhb2ZN8/R6DBMeGFQPAcL3C3E7lEzDxeWVx0h2Zd5dGMGoejzipcaGKtO5m2Q\n8KgL\r\n=dQce\r\n-----END PGP SIGNATURE-----\r\n"},"jest":{"testPathIgnorePatterns":["components/","types/"]},"main":"dist/react-use-gesture.js","name":"react-use-gesture","husky":{"hooks":{"pre-commit":"pretty-quick --staged"}},"types":"types","author":{"name":"Paul Henschel"},"module":"dist/react-use-gesture.es.js","readme":"

\n \n

\n

\n \n \n \n

\n

\n These demos are real, click them!\n

\n\n# react-use-gesture\n\n![npm (tag)](https://img.shields.io/npm/v/react-use-gesture/next.svg) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-use-gesture/5.1.0.svg) ![NPM](https://img.shields.io/npm/l/react-use-gesture/next.svg) [![BuildStatus](https://travis-ci.org/react-spring/react-use-gesture.svg)](https://travis-ci.org/react-spring/react-use-gesture?branch=next)\n\nEver thought about doing that sidebar pull-out, a view pager, some slider, any gesture on the web basically, and dropped the idea because it's too hard? In that case, this is your lib.\n\nReact-use-gesture is a React hook that lets you bind richer mouse and touch events to any component or view. With the data you receive, it becomes trivial to set up gestures, and often takes no more than a few lines of code.\n\nYou can use it stand-alone, but to make the most of it you should combine it with an animation library like [react-spring](https://github.com/react-spring/react-spring), though you can most certainly use any other.\n\n## Installation\n\n```\nnpm install react-use-gesture\n```\n\n## Api\n\n```jsx\nimport { useGesture } from 'react-use-gesture'\n\n// in your component\nconst bind = useGesture(actions, config)\n```\n\nThe api is straight forward. You bind handlers to your view, specify the actions you want to respond to (drag, pinch, hover, move, scroll or wheel) and you will receive events when you interact with the component. These events include the source dom event, but also carry additional kinematics such as velocity, distance, delta, etc.\n\nHooks allow gestures to be re-used for more than one view (you can use the same `bind()` function multiple times!).\n\n```jsx\n// Rough example that makes a div respond to drag and scroll gestures\nfunction myComponent() {\n const bind = useGesture(\n {\n onDrag: dragState => doStuffOnDrag,\n onScroll: scrollState => doStuffOnScroll\n },\n { event: { passive: false } }\n )\n return
\n}\n```\n\n#### Making things move\n\n

\n \n

\n\n```jsx\nfunction myComponent() {\n const [[x, y], set] = React.useState([0, 0])\n const bind = useGesture({ onDrag: ({ local }) => set(local) })\n return
\n}\n```\n\nWhen the user drags the `div` that receives the `{...bind()}` prop, `useGesture` updates the state of the component and the `div` gets positioned accordingly.\n\nIn this case we fetch `local` off the gesture event, which keeps track of delta positions after release. Deltas are especially important in this lib, because they make it possible to use transitions for positioning, instead of doing complex `getBoundingClientRect()` calculations to figure out where a node went on the screen.\n\n#### Avoid re-rendering (preferred)\n\nIn the example we’ve just seen, the component gets re-rendered every time `useGesture` drag handler fires, which can be taxing. To avoid re-rendering you may want to use libraries such as [react-spring](https://github.com/react-spring/react-spring) that allow animating dom elements without setting state, and therefore without triggering new renders.\n\n```jsx\nimport { useSpring, animated } from 'react-spring'\n\nfunction myComponent() {\n const [{ local }, set] = useSpring(() => ({ local: [0, 0] }))\n const bind = useGesture({ onDrag: ({ local }) => set({ local }) })\n\n return `translate3d(${x}px,${y}px,0)`) }} />\n}\n```\n\nBecause we’re now using `animated.div`, we’re able to make the element draggable without provoking new renders every time its position should update.\n\n### Supported gestures\n\nIn addition to **drag**, react-use-gesture also supports **scroll** gesture, and mouse-specific gestures such as **move**, **wheel** and **hover** (entering and leaving an element), and touch-specific **pinch**.\n\nEvery gesture has a handler that should be passed to `useGesture`, and you can pass multiple handlers to the same element for it to respond to different gestures.\n\n```jsx\nconst bind = useGesture({\n onDrag: state => {...}, // fires on drag\n onPinch: state => {...}, // fires on pinch\n onScroll: state => {...}, // fires on scroll\n onHover: state => {...}, // fires on mouse enter, mouse leave\n onMove: state => {...}, // fires on mouse move over the element\n onWheel: state => {...} // fires on mouse wheel over the eleement\n})\n```\n\n### `on[Gesture]Start` and `on[Gesture]End`\n\nDrag, pinch, move, scroll and wheel gestures also have two additional handlers that let you perform actions when they start or end. For example, `onScrollEnd` fires when the user finished scrolling.\n\n> **Note #1:** `on[Gesture]Start` and `on[Gesture]End` methods are provided as a commodity. `on[Gesture]` handlers also receive `first` and `last` properties that indicate if the event fired is the first (i.e. gesture has started) or the last one (i.e. gesture has ended).\n\n```jsx\n// this:\nuseGesture({ onDragStart: doStuffOnStart, onDragEnd:doStuffOnEnd })\n\n// is equivalent to this:\nuseGesture({\n onDrag: ({first, last}) {\n if(first) doStuffOnStart()\n if (last) doStuffOnEnd()\n }\n})\n```\n\n> **Note #2:** since browsers don't have native event listeners for when scroll, move or wheel ends, react-use-gesture debounces these events to estimate when they stopped. One of the consequence of debouncing is trying to access properties from the source event when a gesture has ended will probably result in a warning: [React does event pooling](https://reactjs.org/docs/events.html#event-pooling), meaning a React event can only be queried synchronously.\n\n### Adding gestures to dom nodes\n\nReact-use-gesture also supports adding handlers to dom nodes directly (or the `window` or `document` objects). In that case, you shouldn't spread the `bind()` object returned by `useGesture` as a prop, but use the `React.useEffect` hook as below.\n\n```js\n// this will add a scroll listener to the window\nconst bind = useGesture({ onScroll: state => doStuff }, { domTarget: window })\nReact.useEffect(bind, [bind])\n```\n\nYou can also directly pass a ref to `domTarget`:\n\n```js\nconst myRef = React.useRef(null)\n// this will add a scroll listener the div\nconst bind = useGesture({ onScroll: state => doStuff }, { domTarget: myRef })\nReact.useEffect(bind, [bind])\n/*...*/\nreturn
\n```\n\n> _Note that using `useEffect` will also take care of removing event listeners when the component is unmounted._\n\n### Shortcut to the drag event handler\n\nAlthough React-use-gesture was initially developed to support drag events only (press, move and release), this library now supports pinch, hover, move, scroll and wheel events.\n\nTo ensure retro-compatibility with **v4.x**, **v5.x** still gives you a shortcut to the `onDrag` and pass directly the handler function as the sole argument of `useGesture`.\n\n```jsx\n// this:\nconst bind = useGesture(state => doStuff)\n// is equivalent to this:\nconst bind = useGesture({ onDrag: state => doStuff })\n```\n\n### `useGesture` event state\n\nEvery time a handler is called, it will get passed the current event state for its corresponding gesture. An event state is an object that includes the source event and adds multiple attributes listed below.\n\n#### Shared State\n\nThe following attributes are provided to the handler for all gestures.\n\n| Name | Type | Description |\n| --------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `event` | `object` | source event |\n| `time` | `Number` | timestamp of the current gesture |\n| `first` | `Boolean` | marks the first event |\n| `last` | `Boolean` | marks the last event |\n| `active` | `Boolean` | `true` when the gesture is active, `false` otherwise |\n| `temp` | `Any` | serves as a cache storing any value returned by your handler during its previous run. See below for an example. |\n| `cancel` | `Function` | you can call `cancel` to interrupt the drag or pinch gestures. `cancel`is only relevant for `onDrag` and `onPinch` handlers. |\n| `down` | `Boolean` | mouse / touch down |\n| `touches` | `Number` | number of touches pressing the screen |\n| `shiftKey`
`altKey`
`ctrlKey`
`metaKey` | `Boolean` | modifier keys are pressed |\n| `dragging` | `Boolean` | `true` when the user is dragging |\n| `moving` | `Boolean` | `true` when the user is moving the mouse |\n| `hovering` | `Boolean` | `true` when the mouse hovers the element |\n| `scrolling` | `Boolean` | `true` when the user is scrolling |\n| `wheeling` | `Boolean` | `true` when the user is wheeling |\n| `args` | `Any` | arguments you passed to `bind` |\n\n#### Specific state attributes for X/Y Coordinates Gestures `[drag, scroll, wheel, hover]`\n\nThe following attributes are provided to the handler for gestures that deal with `x/y` coordinates.\n\n| Name | Type | Description |\n| ----------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `xy` | `Vec2 ([x,y])` | for touch/mouse events, `xy` returns the position of the pointer on the screen. For scroll/wheel events `xy` returns how much the element has been scrolled on x and y axis. |\n| `previous` | `Vec2` | previous `xy` |\n| `initial` | `Vec2` | `xy` value when the gesture has started |\n| `delta` | `Vec2` | delta offset (`xy - initial`) |\n| `local` | `Vec2` | delta with book-keeping (remembers the `xy` value throughout gestures) |\n| `lastLocal` | `Vec2` | previous `local` |\n| `vxvy` | `Vec2` | momentum / speed of the gesture (`x` and `y` axis separated) |\n| `velocity` | `Number` | momentum / speed of the gesture (`x` and `y` axis combined) |\n| `distance` | `Number` | delta distance |\n\n#### Specific state attributes for Distance Angle Gestures `[pinch]`\n\nPinch is generally about scaling and rotating. The scale depends on the distance between the two fingers, while the rotation depends on the direction / angle of the vector formed by the two fingers or pointers.\n\n> _More specifically, both scale and rotation depends on the `delta` of `distance` and `angle`, so you will probably end up using `local` or `delta` in most cases._\n\n| Name | Type | Description |\n| ----------- | -------- | ------------------------------------------------------------------------------------------- |\n| `da` | `Vec2` | absolute distance and angle of the two pointers/fingers. |\n| `previous` | `Vec2` | previous `da` |\n| `initial` | `Vec2` | `da` value when the gesture has started |\n| `delta` | `Vec2` | delta offset (`da - initial`) |\n| `local` | `Vec2` | delta with book-keeping (remembers the `da` value throughout gestures) |\n| `lastLocal` | `Vec2` | previous `local` |\n| `vdva` | `Vec2` | momentum / speed of the gesture for distance and angle |\n| `turns` | `Number` | keeps track of the number of turns (don't rely on `turns` to count the number of rotations) |\n\n### `useGesture` config\n\nYou can pass a `config` object as an optional second argument to `useGesture` to customize its behavior.\n\n| Name | Default Value | Description |\n| ----------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `domTarget` | `undefined` | lets you specify a dom node you want to attach gestures to (body, window, document...). You can also pass a ref created with the `useRef` hook. |\n| `event` | `{passive: true, capture: false}` | the event config attribute lets you configure `passive` and `capture` options passed to event listeners. |\n| `transform` | `{x: x => x, y =>y }` | transform functions you can pass to modify `x` and `y` values. |\n| `window` | `window` | lets you specify which `window` element `useGesture` should use. See this [thread](https://github.com/react-spring/react-use-gesture/pull/43#issue-262835054) for a relevant use case. |\n| `enabled` | `true` | enables or disables all gestures |\n| `drag`
`pinch`
`scroll`
`wheel`
`hover`
`move`
| `true` | enables or disables gestures individually |\n\n## Examples\n\n#### `temp` and react-spring\n\n

\n \n
\n Codesandbox\n

\n\nThis demo reads out further data like velocity and direction to calculate decay. `temp` in this case is a simple storage that picks up whatever value you (optionally) return inside the event handler. It's valid as long as the gesture is active. Without this you would need to store the initial xy value somewhere else and conditionally update it when the gesture begins.\n\n```jsx\nconst [{ xy }, set] = useSpring(() => ({ xy: [0, 0] }))\nconst bind = useGesture({\n onDrag: ({ active, delta, velocity, direction, temp = xy.getValue() }) => {\n set({\n xy: add(delta, temp),\n immediate: active,\n config: { velocity: scale(direction, velocity), decay: true }\n })\n return temp\n }\n})\nreturn `translate3d(${x}px,${y}px,0)`) }} />\n```\n\n#### Other examples\n\n- [Locking Axis](https://codesandbox.io/s/25n4m933j)\n\n## Frequently asked questions\n\n**What are the differences between using `useGesture` and adding listeners manually?**\n\nNot a lot! Essentially `useGesture` simplifies the implementation of the drag and pinch gestures, calculates kinematics values you wouldn't get out of the box from the listeners, and debounces move scroll and wheel events to let you know when they end.\n\n**Why `onMove` when `onDrag` already exists?**\n\n`onDrag` only fires while you touch or press the element. You just need to hover your mouse above the element to trigger `onMove`.\n\n**Why `onWheel` and `onScroll`?**\n\nScrolling and wheeling are structurally different events although they produce similar results (i.e. scrolling a page). First of all, `wheel` is a mouse-only event. Then, for `onScroll` to be fired, the element you're scrolling needs to actually scroll, therefore have content overflowing, while you just need to wheel over an element to trigger `onWheel`. If you use [react-three-fiber](https://github.com/drcmda/react-three-fiber), `onWheel` might prove useful to simulate scroll on canvas elements.\n\n**Accessing source event triggers a warning in the console!**\n\nYou're probably trying to access an event in `onScroll`, `onMove` or `onWheel` handlers. The last event is debounced, and therefore not accessible asynchronously because of how React pools events. A possible solution would be to make sure the event is not part of the last state:\n\n```jsx\nuseGesture({\n onScroll: ({ event, last }) => {\n !last && event.preventDefault() // <-- event will not be accessed in the last event\n }\n})\n```\n","gitHead":"b3806cb96d309f31185ec2eba4f9ce2df203a04d","license":"MIT","scripts":{"test":"jest","build":"rollup -c","dtslint":"dtslint types","prepare":"npm run build","prebuild":"rimraf dist","test:watch":"jest --watch","test:coverage":"jest --coverage --silent"},"_npmUser":{"name":"dbismut","email":"david.bismut@gmail.com"},"homepage":"https://github.com/react-spring/react-use-gesture#readme","keywords":["react","hook","gesture","mouse","touch","drag","pinch","scroll","wheel"],"deprecated":"This package is no longer maintained. Please use @use-gesture/react instead","repository":{"url":"git+https://github.com/react-spring/react-use-gesture.git","type":"git"},"_npmVersion":"6.3.0","description":"hook for receiving gestures","directories":{},"maintainers":[{"name":"drcmda","email":"drcmda@gmail.com"}],"sideEffects":false,"_nodeVersion":"8.11.3","contributors":[{"name":"David Bismut"}],"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"jest":"^24.7.1","husky":"^2.2.0","react":"^16.9.0-alpha.0","eslint":"5.x","rimraf":"^2.6.2","rollup":"^1.10.0","dtslint":"^0.7.1","jest-dom":"^3.1.3","prettier":"^1.16.4","react-dom":"^16.9.0-alpha.0","babel-core":"7.0.0-bridge.0","babel-jest":"^24.7.1","typescript":"^3.4.3","@babel/core":"7.4.4","@types/react":"^16.4.18","babel-eslint":"10.x","pretty-quick":"^1.10.0","@babel/preset-env":"^7.4.3","@babel/preset-react":"^7.0.0","eslint-plugin-react":"7.x","rollup-plugin-babel":"^4.3.2","eslint-plugin-import":"2.x","react-testing-library":"^7.0.0","eslint-plugin-flowtype":"2.x","eslint-plugin-jsx-a11y":"6.x","eslint-config-react-app":"^4.0.1","eslint-plugin-react-hooks":"^1.6.0","@babel/plugin-transform-runtime":"7.4.4","@babel/plugin-proposal-class-properties":"^7.4.4","@babel/plugin-transform-modules-commonjs":"^7.4.3"},"peerDependencies":{"react":">= 16.8.0","react-dom":">= 16.8.0"},"_npmOperationalInternal":{"tmp":"tmp/react-use-gesture_5.1.0_1557910301863_0.1075121957641556","host":"s3://npm-registry-packages"},"_id":"react-use-gesture@5.1.0","version":"5.1.0"}