[docs] GestureHandlerRootView (#3970)

m-bert · Copilot · j-piasecki · web-flow · commit 3f91ea59b5a8 · 2026-02-13T13:37:10.000+01:00
## Description

I've found it a bit frustrating that our docs do not have specific entry
for `GestureHandlerRootView`, even though they reference it pretty
often. Also because of that `installation` page served a purpose of
component description, rather than showing quick setup.

I've extracted root view information to specific page in
**fundamentals** section

## Test plan

Read docs 🤓

---------

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
Co-authored-by: Jakub Piasecki &lt;jakub.piasecki@swmansion.com&gt;
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -47,7 +47,7 @@ Setting up `react-native-gesture-handler` is pretty straightforward:
   </TabItem>
 </Tabs>
 
-### 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 `<GestureHandlerRootView>`, you can try adding another `<GestureHandlerRootView unstable_forceActive>` 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
@@ -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
@@ -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 (
+    <GestureHandlerRootView>
+      <ActualApp />
+    </GestureHandlerRootView>
+  );
+}
+```
+
+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 `<GestureHandlerRootView>`, you can try adding another `<GestureHandlerRootView unstable_forceActive>` 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
@@ -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
@@ -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
@@ -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...).
