diff --git a/packages/docs-gesture-handler/docs/components/pressable.mdx b/packages/docs-gesture-handler/docs/components/pressable.mdx index 5d717b4fc2..b280113b24 100644 --- a/packages/docs-gesture-handler/docs/components/pressable.mdx +++ b/packages/docs-gesture-handler/docs/components/pressable.mdx @@ -17,7 +17,7 @@ This component is a drop-in replacement for the `Pressable` component. `Pressable` is a component that can detect various stages of tap, press, and hover interactions on any of its children. -To use `Pressable`, ensure that your app is wrapped in `GestureHandlerRootView` and import it as follows: +To use `Pressable`, ensure that your app is wrapped in [`GestureHandlerRootView`](/docs/fundamentals/root-view) and import it as follows: ```ts import { Pressable } from 'react-native-gesture-handler'; diff --git a/packages/docs-gesture-handler/docs/components/reanimated-drawer-layout.mdx b/packages/docs-gesture-handler/docs/components/reanimated-drawer-layout.mdx index 6446f11be3..d9e8fefc45 100644 --- a/packages/docs-gesture-handler/docs/components/reanimated-drawer-layout.mdx +++ b/packages/docs-gesture-handler/docs/components/reanimated-drawer-layout.mdx @@ -10,7 +10,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; This component acts as a cross-platform replacement for React Native's [`DrawerLayoutAndroid`](http://reactnative.dev/docs/drawerlayoutandroid.html) component, written using [Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started). For detailed information on standard parameters, please refer to the [React Native documentation](http://reactnative.dev/docs/drawerlayoutandroid.html). ::: -To use `ReanimatedDrawerLayout`, first ensure that Reanimated is installed and that your app is wrapped in `GestureHandlerRootView`. You can then import it as follows: +To use `ReanimatedDrawerLayout`, first ensure that Reanimated is installed and that your app is wrapped in [`GestureHandlerRootView`](/docs/fundamentals/root-view). You can then import it as follows: ```ts import ReanimatedDrawerLayout from 'react-native-gesture-handler/ReanimatedDrawerLayout'; diff --git a/packages/docs-gesture-handler/docs/fundamentals/animated-interactions.mdx b/packages/docs-gesture-handler/docs/fundamentals/animated-interactions.mdx index bca2e3e4a6..0f6cc5d060 100644 --- a/packages/docs-gesture-handler/docs/fundamentals/animated-interactions.mdx +++ b/packages/docs-gesture-handler/docs/fundamentals/animated-interactions.mdx @@ -2,7 +2,7 @@ id: animated-interactions title: Integration with Animated sidebar_label: Integration with Animated -sidebar_position: 5 +sidebar_position: 9 --- import CollapsibleCode from '@site/src/components/CollapsibleCode'; diff --git a/packages/docs-gesture-handler/docs/fundamentals/callbacks-events.mdx b/packages/docs-gesture-handler/docs/fundamentals/callbacks-events.mdx index e5c0a3bca2..4ac1d88dd1 100644 --- a/packages/docs-gesture-handler/docs/fundamentals/callbacks-events.mdx +++ b/packages/docs-gesture-handler/docs/fundamentals/callbacks-events.mdx @@ -2,7 +2,7 @@ id: callbacks-events title: Gesture callbacks & events sidebar_label: Gesture callbacks & events -sidebar_position: 7 +sidebar_position: 6 --- import { GestureEventFlowChart, TouchEventFlowChart } from '@site/src/examples/CallbacksFlowCharts' diff --git a/packages/docs-gesture-handler/docs/fundamentals/gesture-composition.mdx b/packages/docs-gesture-handler/docs/fundamentals/gesture-composition.mdx index c23566899d..156407c8af 100644 --- a/packages/docs-gesture-handler/docs/fundamentals/gesture-composition.mdx +++ b/packages/docs-gesture-handler/docs/fundamentals/gesture-composition.mdx @@ -2,7 +2,7 @@ id: gesture-composition title: Gesture composition & interactions sidebar_label: Gesture composition & interactions -sidebar_position: 6 +sidebar_position: 5 --- import CollapsibleCode from '@site/src/components/CollapsibleCode'; diff --git a/packages/docs-gesture-handler/docs/fundamentals/gesture-detector.mdx b/packages/docs-gesture-handler/docs/fundamentals/gesture-detector.mdx index 99a10cdd45..cf88c68a7b 100644 --- a/packages/docs-gesture-handler/docs/fundamentals/gesture-detector.mdx +++ b/packages/docs-gesture-handler/docs/fundamentals/gesture-detector.mdx @@ -2,7 +2,7 @@ id: gesture-detectors title: Gesture Detectors sidebar_label: Gesture detectors -sidebar_position: 3 +sidebar_position: 4 --- import CollapsibleCode from '@site/src/components/CollapsibleCode'; diff --git a/packages/docs-gesture-handler/docs/fundamentals/installation.mdx b/packages/docs-gesture-handler/docs/fundamentals/installation.mdx index c1500b2c75..e57893ef5d 100644 --- a/packages/docs-gesture-handler/docs/fundamentals/installation.mdx +++ b/packages/docs-gesture-handler/docs/fundamentals/installation.mdx @@ -47,7 +47,7 @@ Setting up `react-native-gesture-handler` is pretty straightforward: -### 2. Wrap your app with `GestureHandlerRootView` component +### 2. Wrap your app with GestureHandlerRootView component ```jsx import { GestureHandlerRootView } from 'react-native-gesture-handler'; @@ -62,21 +62,7 @@ export default function App() { ``` Keep `GestureHandlerRootView` as close to the actual root of the app as possible. It's the entry point for all gestures and all [gesture relations](/docs/fundamentals/gesture-composition). The gestures won't be recognized outside of the root view, and relations only work between gestures mounted under the same root view. -If you don't provide anything to the `styles` prop, it will default to `flex: 1`. If you want to customize the styling of the root view, don't forget to also include `flex: 1` in the custom style, otherwise your app won't render anything. - -If you're unsure if one of your dependencies already renders `GestureHandlerRootView` on its own, don't worry and add one at the root anyway. In case of nested root views, Gesture Handler will only use the top-most one and ignore the nested ones. - -:::note -Remember that you need to wrap each screen that you use in your app with `GestureHandlerRootView` as with native navigation libraries each screen maps to a separate root view. It will not be enough to wrap the main screen only. -::: - -#### Using `GestureHandlerRootView` with third party libraries - -If you're having trouble with gestures not working when inside a component provided by a third-party library, even though you've wrapped the entry point with ``, you can try adding another `` closer to the place the gestures are defined. This way, you can prevent Android from canceling relevant gestures when one of the native views tries to grab lock for delivering touch events. - -:::tip -If you're using Gesture Handler in your component library, you may want to wrap your library's code in the `GestureHandlerRootView` component. This will avoid extra configuration for the user. -::: +Check out [`GestureHandlerRootView`](/docs/fundamentals/root-view) section for more details. ### 3. Platform specific setup diff --git a/packages/docs-gesture-handler/docs/fundamentals/reanimated-interactions.mdx b/packages/docs-gesture-handler/docs/fundamentals/reanimated-interactions.mdx index df2d223211..ff74d76c94 100644 --- a/packages/docs-gesture-handler/docs/fundamentals/reanimated-interactions.mdx +++ b/packages/docs-gesture-handler/docs/fundamentals/reanimated-interactions.mdx @@ -2,7 +2,7 @@ id: reanimated-interactions title: Integration with Reanimated sidebar_label: Integration with Reanimated -sidebar_position: 4 +sidebar_position: 8 --- import CollapsibleCode from '@site/src/components/CollapsibleCode'; diff --git a/packages/docs-gesture-handler/docs/fundamentals/root-view.mdx b/packages/docs-gesture-handler/docs/fundamentals/root-view.mdx new file mode 100644 index 0000000000..362de2d34f --- /dev/null +++ b/packages/docs-gesture-handler/docs/fundamentals/root-view.mdx @@ -0,0 +1,48 @@ +--- +id: root-view +title: GestureHandlerRootView +sidebar_label: GestureHandlerRootView +sidebar_position: 3 +--- + +`GestureHandlerRootView` is a key component that enables Gesture Handler to intercept touch events, allowing for the implementation of gestures in your app. It should wrap your app's main component, and any component that relies on Gesture Handler's gestures has to be a descendant of this view. For more detailed information, you can check out the [under-the-hood section](/docs/under-the-hood/how-does-it-work#android). + +```tsx +import { GestureHandlerRootView } from 'react-native-gesture-handler'; + +export default function App() { + return ( + + + + ); +} +``` + +Keep `GestureHandlerRootView` as close to the actual root of the app as possible. It's the entry point for all gestures and all [gesture relations](/docs/fundamentals/gesture-composition). The gestures won't be recognized outside of the root view, and relations only work between gestures mounted under the same root view. + +:::note +When integrating with navigation libraries, wrapping the navigator component with `GestureHandlerRootView` is generally sufficient. However, if you encounter issues with gestures not functioning properly, you might need to wrap each individual screen component with `GestureHandlerRootView` as well. +::: + +:::tip +If you're using Gesture Handler in your component library, you may want to wrap your library's code in the `GestureHandlerRootView` component. This will avoid extra configuration for the user. +::: + +## Styling + +`GestureHandlerRootView` can be thought of as a regular `View` component, therefore it accepts all the same props, including [`style`](https://reactnative.dev/docs/0.81/view-style-props). + +If you don't provide anything to the `style` prop, it will default to `{ flex: 1 }`. If you want to customize the styling of the root view, don't forget to also include `flex: 1` in the custom style, otherwise your app won't render anything. + +## Nesting root views + +In case of nested root views, Gesture Handler will only use the top-most one and ignore the nested ones. If you're unsure if one of your dependencies already renders `GestureHandlerRootView` on its own, don't worry and add one at the root anyway. + +## unstable_forceActive + +```ts +unstable_forceActive?: boolean; +``` + +If you're having trouble with gestures not working when inside a component provided by a third-party library, even though you've wrapped the entry point with ``, you can try adding another `` closer to the place the gestures are defined. This way, you can prevent Android from canceling relevant gestures when one of the native views tries to grab lock for delivering touch events. diff --git a/packages/docs-gesture-handler/docs/fundamentals/state-manager.mdx b/packages/docs-gesture-handler/docs/fundamentals/state-manager.mdx index cd310af2cd..ab685ff241 100644 --- a/packages/docs-gesture-handler/docs/fundamentals/state-manager.mdx +++ b/packages/docs-gesture-handler/docs/fundamentals/state-manager.mdx @@ -2,7 +2,7 @@ id: state-manager title: State manager sidebar_label: State manager -sidebar_position: 6 +sidebar_position: 7 --- import CollapsibleCode from '@site/src/components/CollapsibleCode'; diff --git a/packages/docs-gesture-handler/docs/guides/troubleshooting.mdx b/packages/docs-gesture-handler/docs/guides/troubleshooting.mdx index cc96be56fb..5540dd2588 100644 --- a/packages/docs-gesture-handler/docs/guides/troubleshooting.mdx +++ b/packages/docs-gesture-handler/docs/guides/troubleshooting.mdx @@ -33,7 +33,7 @@ This library is maintained by a very small team. Please keep this in mind when r - Changing `enabled` prop during a gesture has no effect, only when a gesture starts (that is a finger touches the screen) the `enabled` prop is taken into consideration to decide whether to extract (or not) the gesture and provide it with stream of events to analyze. - `Native` gesture may not conform to the standard state flow due to platform specific workarounds to incorporate native views into RNGH. - Keep in mind that [`Touchables`](/docs/components/touchables) from RNGH are rendering two additional views that may need to be styled separately to achieve desired effect (`style` and `containerStyle` props). -- In order for the [gesture composition](/docs/fundamentals/gesture-composition) to work, all composed gestures must be attached to the same `GestureHandlerRootView`. +- In order for the [gesture composition](/docs/fundamentals/gesture-composition) to work, all composed gestures must be attached to the same [`GestureHandlerRootView`](/docs/fundamentals/root-view). ## Multiple instances of Gesture Handler were detected diff --git a/packages/docs-gesture-handler/docs/under-the-hood/how-does-it-work.md b/packages/docs-gesture-handler/docs/under-the-hood/how-does-it-work.md index 59e22b57ba..135cc59043 100644 --- a/packages/docs-gesture-handler/docs/under-the-hood/how-does-it-work.md +++ b/packages/docs-gesture-handler/docs/under-the-hood/how-does-it-work.md @@ -17,6 +17,6 @@ All gestures are implemented using [UIGestureRecognizers](https://developer.appl ## Android Unfortunately, Android doesn't provide an easy way of handling gestures hence most of them were implemented from scratch, including a system for managing how the gestures should interact with each other. Here's a quick overview of how it works: -When you wrap a component with `GestureHandlerRootView` it allows for the RNGH to intercept all touch events on that component and process them, deciding whether they should be handled by one of the gesture handlers or passed to the underlying view. Gesture handlers are created right at the moment you declare them in order to initialize all of the necessary handlers natively. Every `GestureHandlerRootView` also has a specific handler to decide whether to pass the touch events or to consume them. It can never activate, only begin, end or be cancelled. When this handler is in the `UNDETERMINED` [state](/docs/under-the-hood/state) it means that there is no touch in progress, however when the touch starts it transitions to the `BEGAN` state. As long as it stays in that state, no touch event is consumed, but as soon as it gets cancelled (meaning that some handler has activated) all incoming touch events get consumed, preventing underlying view from receiving them. +When you wrap a component with [`GestureHandlerRootView`](/docs/fundamentals/root-view) it allows for the RNGH to intercept all touch events on that component and process them, deciding whether they should be handled by one of the gesture handlers or passed to the underlying view. Gesture handlers are created right at the moment you declare them in order to initialize all of the necessary handlers natively. Every `GestureHandlerRootView` also has a specific handler to decide whether to pass the touch events or to consume them. It can never activate, only begin, end or be cancelled. When this handler is in the `UNDETERMINED` [state](/docs/under-the-hood/state) it means that there is no touch in progress, however when the touch starts it transitions to the `BEGAN` state. As long as it stays in that state, no touch event is consumed, but as soon as it gets cancelled (meaning that some handler has activated) all incoming touch events get consumed, preventing underlying view from receiving them. When a pointer touches the screen the view tree is traversed in order to extract all handlers attached to the views below the finger (including the one attached to the `GestureHandlerRootView`) and all extracted handlers transition to the `BEGAN` state, signalling that the gesture may have began. The touch events continue to be delivered to all extracted handlers until one of them recognizes the gesture and tries to activate. At this point the orchestrator checks whether this gesture should wait for any other of the extracted gestures to fail. If it does, it's put to the waiting list, if it doesn't, it gets activated and all other gestures (that are not simultaneous with it) get cancelled. When a gesture handlers transitions to a finished state (the gesture recognized by it stops, fails or gets cancelled) the orchestrator checks the waiting handlers. Every one of them that waited for the gesture that just failed tries to activate again (and again the orchestrator checks if it should wait for any of the extracted gestures...).