Native way of handling touch & gestures for React Native apps!
This library provides an API that exposes mobile platform specific native capabilities of touch & gesture handling and recognition. It allows for defining complex gesture handling and recognition logic that runs 100% in native thread and is therefore deterministic.
- It provides a way to access native touch handling logic for recognizing pinch, rotation, pan and other
- You can define relations between gesture handlers, e.g. when you have pan handler in scrollview you can make scrollview to wait until it knows pan won't recognize
- You can use touchables that run in native and follow platform default behaviour in case when they are embbede in scrollable component (the interaction is slightly delayed to prevent button from highlighting when you fling)
- You can implement smooth gesture interactions that thanks to "Animated Native Driver" can run even when JS thread is overloaded
Before instaling please check the following table to find which library version is compatible with React Native version you are using:
| React Native version | React Native Gesture Handler version | Notes |
|---|---|---|
| v0.50+ | latest | |
| v0.47 - v0.49 | 1.0.0-alpha.29 | Breaking changes explained and fixed in #44 |
| pre v0.47 | Not supported |
I. First install the library from npm repository using yarn:
yarn add react-native-gesture-handleror using npm if you prefer:
npm install --save react-native-gesture-handlerII. Run:
react-native link react-native-gesture-handlerIII (Android). Follow the steps below:
IMPORTANT: If you use one of the native navigation libraries (e.g. wix/react-native-navigation), you need to follow this separate guide to get gesture handler library set up on Android. Ignore the rest of this step – it only applies to RN apps that uses standard Android project layout.
Update your main activity (or wherever you create an instance of ReactActivityDelegate), so that it overrides the method responsible for creating a ReactRootView instance. Then use a root view wrapper provided by this library:
// Don't forget imports
import com.facebook.react.ReactActivityDelegate;
import com.facebook.react.ReactRootView;
import com.swmansion.gesturehandler.react.RNGestureHandlerEnabledRootView;
public class MainActivity extends ReactActivity {
// Add the following method to your main activity class
@Override
protected ReactActivityDelegate createReactActivityDelegate() {
return new ReactActivityDelegate(this, getMainComponentName()) {
@Override
protected ReactRootView createRootView() {
return new RNGestureHandlerEnabledRootView(MainActivity.this);
}
};
}
}III (iOS). There is no additional config required to be done on iOS except from what follows in the next steps.
IV. You're all set, just run your app with react-native run-android or react-native run-ios
If you don't feel like trying it on a real app, but just want to play with the API you can run the example project. Clone the repo, go to the Example/ folder and run:
yarn installThen run react-native run-android or react-native run-ios depending on which platform you want to run the example app on.
You will need to have an Android or iOS device or emulator connected as well as react-native-cli package installed globally.
Here are a gesture recognizers currently available in the package:
TapGestureHandlerLongPressGestureHandlerPanGestureHandlerPinchGestureHandlerRotationGestureHandler
Whenever you use a native component that should handle touch events you can either wrap it with NativeViewGestureHandler or import wrapper component exported by the library instead of importing it from react-native package. Here is the list of available components:
ScrollViewSliderSwitchTextInputToolbarAndroid(Android only)ViewPagerAndroid(Android only)DrawerLayoutAndroid(Android only)WebView
Library exports a State object that provides a number of constants used to express the state of the handler. Here are the available constants:
State.UNDETERMINED- default and initial stateState.FAILED- handler failed recognition of the gestureState.BEGAN- handler has initiated recognition but have not enough data to tell if it has recognized or notState.CANCELLED- handler has been cancelled because of other handler (or a system) stealing the touch streamState.ACTIVE- handler has recognizedState.END- gesture has completed
idenabledshouldCancelWhenOutsidesimultaneousHandlerswaitForhitSlop(accepts only negative values on iOS)onGestureEventonHandlerStateChange
maxDurationMsmaxDelayMsnumberOfTaps
shouldActivateOnStartdisallowInterruption
minDurationMs
minDeltaXminDeltaYmaxDeltaXmaxDeltaYminOffsetXminOffsetYminDistminVelocityminVelocityXminVelocityYminPointersmaxPointersavgTouches(Android only)
Gesture handler library provides native components that can act as buttons. These can be treated as a replacement to TouchableHighlight or TouchableOpacity from RN core. Gesture handler's buttons recognize touches in native which makes the recognition process deterministic, allows for rendering ripples on android in performant way (with TouchableNativeFeedback it is required that touch event to a roundtrip to JS before we can update ripple which makes ripples lag a bit on older phones), and provides native and platform default interaction for buttons that are placed in a scrollable container (in which case the interaction is slightly delay to prevent button from highlighting when you fling).
Currently Gesture handler library exposes three components that renders native touchable elements under the hood:
BaseButtonRectButtonBorderlessButton
On top of that all the buttons are wrapped with NativeViewGestureHandler and therefore allow for all the common gesture handler properties and NativeViewGestureHandler's extra properties to be applied to them.
Can be used as a base class if you'd like to implement some custom interaction for when the button is pressed. The following props can be used:
onActiveStateChange- function that gets triggered when button changes from inactive to active and vice versa. It passes active state as a boolean variable as a first parameter for that method.onPress- function that gets triggered when the button gets pressed (similar to how it works withTouchableHighlightfrom RN core).
This type of a button component should be used when you deal with a rectangular elements or blocks of content that can be pressed, like table rows or buttons with text and icons. This component provides a platform specific interaction rendering a rectangular ripple on android or highlighting the background on iOS and on older versions of android. Along with all the properties of BaseButton it allows for specifying the following props:
underlayColor- this is the background color that will be dimmed when button is in active state.activeOpacity(iOS only) - opacity applied to the underlay when button is in active state.
This type of a button component should be used with simple icon-only or text-only buttons. The interaction will be different depending on platform: on android a borderless ripple will be rendered (it means that the ripple will animate into a circle that can span outside of the view bounds) whereas on iOS the button will be dimmed (similar to how TouchableOpacity works). Along with all the properties of BaseButton it allows for specifying the following props:
borderless(Android only) - set this tofalseif you want the ripple animation to render only within view bounds.activeOpacity(iOS only) - opacity applied to the button when it is in an active state.
Gesture handler library API allows for defining some basic interaction between handler components. Interactions can be defined by first setting a string identifer for a handler component with id property and then referencing it with waitFor or simultaneousHandlers props in other handler component.
This property accepts a single string ID of a gesture handler or an array of string IDs. When set for a given gesture handler it will make it wait for the handler(s) with the given ID(s) to fail before it can activate.
This property accepts a single string ID of a gesture handler or an array of string IDs. When set for a given gesture handler it allow for this gesture handler to recognize simultaneousy with handler(s) with the given ID(s). One popular usecase is with a photo that can be pinched and rotated, in which case we want both pinch and rotate gesture handlers to recognize simultaneously.
Gesture handler library makes it possible for some interations to be build in much more performant way that it was possible with PanHandler. To illustrate this we decided to build a couple of components that are already available for react-native apps but often are build using PanResponder API which results in poor performance.
This is a cross platform replacement for react-native's DrawerLayoutAndroid component. It provides a compatible API but allows for the component to be used on both Android and iOS. Please refer to react-native docs for the detailed usage for standard parameters.
As the DrawerLayout component isn't expored by default from the gesture-handler package in order to use it import it in the following way:
import DrawerLayout from 'react-native-gesture-handler/DrawerLayout';On top of the standard list of parameters DrawerLayout has an additional set of attributes that helps with customizing its behavior. Please refer to the list below:
drawerType– possible values are:front,backorslide(default isfront). It specifies the way drawer will be displayed. When set tofrontdrawer will slide in/out along with the gesture and will display on top of the content view. Whenbackis used the drawer displays below the content view and can be revealed with the gesture that will pull the content view to the side. Finallyslideoption make the drawer appear like it is sticked to the side of the content view and when you pull both content view and drawer will follow the gesture.edgeWidth– number, allows for defining how far from the edge of the content view the gesture should activate.hideStatusBar– boolean, when set totrueDrawer component will use StatusBar API to hide the OS status bar whenever the drawer is pulled or when its in an "open" state.statusBarAnimation– possible values are:slide,noneorfade(defaults toslide). Can be used whenhideStatusBaris set totrueand allows for defining the animation used for hiding/showing the status bar. See StatusBar documentation for more details.overlayColor– color (default to"black") of a semi-transparent overlay to be displayed on top of the content view when drawer gets open. A solid color should be used as the opacity is added by the Drawer itself and the opacity of the overlay is animated (from 0% to 70%).renderNavigationView- function. This attibute is present in the standard implementation already and is one of the required params. Gesture handler version of DrawerLayout make it possible for the function passed asrenderNavigationViewto take an Animated value as a parameter that indicates the progress of drawer opening/closing animation (progress value is 0 when closed and 1 when opened). This can be used by the drawer component to animated its children while the drawer is opening or closing.
An example code that that uses DrawerLayout component can be found here: horizontalDrawer/index.js
This component allows for implementing swipeable rows or similar interaction. It renders its children within a panable container allows for horizontal swiping left and right. While swiping one of two "action" containers can be shown depends on whether user swipes left or right (containers can be rendered by renderLeftActions or renderRightActions props).
Similarly to the DrawerLayout, Swipeable component isn't expored by default from the gesture-handler package in order to use it import it in the following way:
import Swipeable from 'react-native-gesture-handler/Swipeable';friction– a number that specifies how much the visual interation will be delayed compared to the gesture distance. e.g. value of 1 will indicate that the swipeable panel should exactly follow the gesture, 2 means it is going to be two times "slower".leftThreshold– diance from the left edge at which released panel will animate to the open state (or the open panel will animate into the closed state). By default it's a half of the panel's width.rightThreshold– diance from the right edge at which released panel will animate to the open state (or the open panel will animate into the closed state). By default it's a half of the panel's width.overshootLeft– a boolean value indicating if the swipeable panel can be pulled further than the left actions panel's width. It is set totrueby default as long as the left panel render method is present.overshootRight– a boolean value indicating if the swipeable panel can be pulled further than the right actions panel's width. It is set totrueby default as long as the right panel render method is present.onSwipeableLeftOpen– method that is called when left action panel gets open.onSwipeableRightOpen– method that is called when right action panel gets open.onSwipeableOpen– method that is called when action panel gets open (either right or left).onSwipeableClose– method that is called when action panel is closed.renderLeftActions– method that is expected to return an action panel that is going to be revealed from the left side when user swipes right.renderRightActions– method that is expected to return an action panel that is going to be revealed from the right side when user swipes left.
An example code that that uses Swipeable component can be found here: swipeable/index.js
This project is still in alpha so it is not suprising you're seeking help. Try searching over the issues on GitHub here. If you don't find anything that would help feel free to open a new issue!
If you are interested in the project and want to contribute or support it in other ways don't hesitate to contact me! Also all PRs are always welcome!
This project is supported by amazing people from Expo.io and Software Mansion
