diff --git a/docs/docs/gestures/native-gesture.md b/docs/docs/gestures/native-gesture.md index f9758b53ec..583a25436d 100644 --- a/docs/docs/gestures/native-gesture.md +++ b/docs/docs/gestures/native-gesture.md @@ -10,36 +10,77 @@ import BaseEventConfig from './\_shared/base-gesture-config.md'; import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; import BaseContinuousEventCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; -A gesture that allows other touch handling components to participate in RNGH's gesture system. When used, the other component should be the direct child of a `GestureDetector`. +A gesture that allows other touch handling components to work within RNGH's gesture system. This streamlines interactions between gestures and the native component, allowing it to form [relations](/docs/fundamentals/gesture-composition) with other gestures. -## Reference +When used, the native component should be the direct child of a `GestureDetector`. + +## Example + +This example renders a `ScrollView` with multiple colored rectangles, where each rectangle has a black section. Starting a touch on a black section will disable the `ScrollView` for the duration of the `Pan` gesture. ```jsx -import { GestureDetector, Gesture } from 'react-native-gesture-handler'; +import { View, ScrollView } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; -function App() { +const COLORS = ['red', 'green', 'blue', 'purple', 'orange', 'cyan']; + +export default function App() { // highlight-next-line const native = Gesture.Native(); return ( - + + + ); } + +function ScrollableContent({ scrollGesture }) { + return ( + + {COLORS.map((color) => ( + + ))} + + ); +} + +function Rectangle({ color, scrollGesture }) { + const pan = Gesture.Pan().blocksExternalGesture(scrollGesture); + + return ( + + + + + + ); +} ``` +## Remarks + +- `Native` gesture can be used as part of [gesture composition and cross-component interactions](/docs/fundamentals/gesture-composition) just like any other gesture. You can use this to block a native component for the duration of the gesture or to make it work alongside a gesture. + +:::danger +Do not use `Native` gesture with components exported by React Native Gesture Handler. Those come with a native gesture handler preapplied. Attaching a native gesture twice will likely result in the components not working as intended. +::: + ## Config ### Properties specific to `NativeGesture`: ### `shouldActivateOnStart(value: boolean)` (**Android only**) -When `true`, underlying handler will activate unconditionally when in `BEGAN` or `UNDETERMINED` state. +When `true`, underlying handler will activate unconditionally when it receives any touches in [`BEGAN`](/docs/fundamentals/states-events#began) or [`UNDETERMINED`](/docs/fundamentals/states-events#undetermined) state. ### `disallowInterruption(value: boolean)` -When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` receives an `ACTIVE` state event. +When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` changes its state to [`ACTIVE`](/docs/fundamentals/states-events#active).