Every time a handler is called, it will get passed a gesture state that includes the source event and adds multiple attributes such as velocity, previous value, and much more.
States structure doesn't vary much across different gestures: the only distinction comes from the
pinch gesture which handles
angle values (how distant your fingers are on screen, and what is their angle), when all other hooks deal with
xy gestures state attributes
With the exception of
vxvy, all the attributes below are common to all gestures.
pinch state attributes
The state attributes for
pinch include all of the above (with the exception of
vxvy) plus the one below:
drag state attributes
drag gesture state adds a few attributes which can help you understand the user intent.
offset are the attributes you're going to use most of the time when dragging or pinching. They represent relative values of the gesture, in contrast with
da which are absolute values of your pointers. Relative values are handy as you usually use the
transform style attribute to move your components, which itself is relative to the component natural position.
The difference between the two
In React-use-gesture, we call gesture the act of the user initiating and terminating an interaction.
movement expresses the gesture movement, while
offset is the sum of all gesture movements on the same component. When you start dragging a component,
movement is reset to
offset keeps its previous value.
In practical terms,
movement is handy when your element returns back to its original position at the end of the gesture. Here is an example for
offset, where the component stays where you left it:
memo stores the value returned by the previous call of your handler. The most common usecase for using
memo should be simplified by using
cancel is a function that imperatively stops the current gesture. Here is an example on how you might want to use
cancel with the drag gesture.
If you drag the blue square over the pink zone, you'll notice that the gesture is canceled and the blue square goes back to its original position. This is very simply triggered using the code below.
This is obviously very simple abstract logic, but please go over the Examples section for more compelling use cases. Note that only
pinch gestures are cancellable (calling
cancel on other gestures won't do anything).
swipe (drag only)
swipe is a convenient state attribute for the drag gesture that will help you detect swipes.
swipe is a vector which both components are either
1. The component stays to
0 until a swipe is detected.
-1 indicates the direction of the swipe (left or right on the horizontal axis, top or bottom on the vertical axis).
In the example above, the blue square will move left or right when you swipe it. Here is the code to make it happen:
Here are the conditions for a swipe to be detected on the
- The drag gesture is over.
- The drag gesture didn't last more than
movementis superior to the
vxvyis superior to the
Visit the swipe options documentation for more info about how to configure swipe detection to your needs.
tap (drag only)
tap is a
boolean state attribute for the drag gesture that will be set to true if the drag gesture can be assimilated to a tap or click. In other words,
tap will be
true on mouse or touch release only when the drag displacement is inferior to
You'll usually want to use the
tap attribute in conjunction with the