[docs] GestureHandlerRootView
#3970
Conversation
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…or.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…t-native-gesture-handler into @mbert/docs-review
Co-authored-by: Jakub Piasecki <jakub.piasecki@swmansion.com>
Co-authored-by: Jakub Piasecki <jakub.piasecki@swmansion.com>
….mdx Co-authored-by: Jakub Piasecki <jakub.piasecki@swmansion.com>
…eact-native-gesture-handler into @mbert/docs-root-view
…t-native-gesture-handler into @mbert/docs-review
There was a problem hiding this comment.
Pull request overview
This PR reorganizes the Gesture Handler documentation by extracting GestureHandlerRootView guidance into a dedicated Fundamentals page, and updating existing docs to link to it so the Installation page focuses more on setup.
Changes:
- Add a new Fundamentals doc page for
GestureHandlerRootView. - Replace scattered inline mentions of
GestureHandlerRootViewwith links to the new page. - Reorder Fundamentals sidebar positions to accommodate the new page.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/docs-gesture-handler/docs/under-the-hood/how-does-it-work.md | Links GestureHandlerRootView mention to the new Fundamentals page. |
| packages/docs-gesture-handler/docs/guides/troubleshooting.mdx | Links GestureHandlerRootView mention to the new Fundamentals page. |
| packages/docs-gesture-handler/docs/fundamentals/root-view.mdx | New dedicated page documenting GestureHandlerRootView, styling, nesting, and unstable_forceActive. |
| packages/docs-gesture-handler/docs/fundamentals/installation.mdx | Removes detailed root-view explanation and points readers to the new page. |
| packages/docs-gesture-handler/docs/fundamentals/gesture-detector.mdx | Sidebar reorder to account for new page position. |
| packages/docs-gesture-handler/docs/fundamentals/gesture-composition.mdx | Sidebar reorder to account for new page position. |
| packages/docs-gesture-handler/docs/fundamentals/callbacks-events.mdx | Sidebar reorder to account for new page position. |
| packages/docs-gesture-handler/docs/fundamentals/state-manager.mdx | Sidebar reorder to account for new page position. |
| packages/docs-gesture-handler/docs/fundamentals/reanimated-interactions.mdx | Sidebar reorder to account for new page position. |
| packages/docs-gesture-handler/docs/fundamentals/animated-interactions.mdx | Sidebar reorder to account for new page position. |
| packages/docs-gesture-handler/docs/components/reanimated-drawer-layout.mdx | Links wrapping requirement to the new root-view page. |
| packages/docs-gesture-handler/docs/components/pressable.mdx | Links wrapping requirement to the new root-view page. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ## 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). |
There was a problem hiding this comment.
The React Native docs link is pinned to a specific version (0.81). This will go stale and is inconsistent with the rest of the docs here; consider using the unversioned React Native URL (e.g. /docs/view-style-props) so the link stays valid across RN minor versions.
| `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). | |
| `GestureHandlerRootView` can be thought of as a regular `View` component, therefore it accepts all the same props, including [`style`](https://reactnative.dev/docs/view-style-props). |
| ## 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. |
There was a problem hiding this comment.
The “Nesting root views” section says nested root views are ignored, but later the page recommends adding a nested GestureHandlerRootView unstable_forceActive. On Android, nested root views are disabled by default but can be enabled when unstable_forceActive is set, so this section should clarify that nested root views are ignored unless unstable_forceActive forces the nested one to become active.
| 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. |
There was a problem hiding this comment.
The navigation note is a bit ambiguous: it suggests wrapping the navigator is usually enough and wrapping individual screens is only needed when issues occur. However, the installation docs still state that with native navigation libraries (e.g. wix/react-native-navigation) each screen must be wrapped because each screen maps to a separate root view. Consider updating this note to explicitly call out that distinction (JS-based nav vs native nav) or linking directly to the relevant installation section to avoid misconfiguration.
| 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. | |
| For JavaScript-based navigation libraries (such as React Navigation), wrapping the top-level navigator component with `GestureHandlerRootView` is generally sufficient because all screens share a single React Native root view. For native navigation libraries (such as `wix/react-native-navigation`), each native screen is its own root view, so **each screen component must be wrapped** with `GestureHandlerRootView`, as described in the [installation guide](/docs/installation). |
3 participants
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 thatinstallationpage 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 🤓