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).