From 4e3e30f4a4660124f11e2ab58d7ef4d706213450 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Tue, 9 Dec 2025 18:11:27 +0100 Subject: [PATCH 01/45] Pan gesture --- .../base-continuous-gesture-callbacks.md | 9 + .../hooks/_shared/base-gesture-callbacks.md | 77 ++++ .../docs/hooks/_shared/base-gesture-config.md | 116 ++++++ .../hooks/_shared/base-gesture-event-data.md | 27 ++ .../docs/hooks/use-pan-gesture.md | 347 ++++++++++++++++++ 5 files changed, 576 insertions(+) create mode 100644 packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-callbacks.md create mode 100644 packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.md create mode 100644 packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md create mode 100644 packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-event-data.md create mode 100644 packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-callbacks.md b/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-callbacks.md new file mode 100644 index 0000000000..446234e8ff --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-callbacks.md @@ -0,0 +1,9 @@ +### Callbacks common to all continuous gestures: + +### onUpdate + +```ts +onUpdate: (event: HandlerData) => void +``` + +Set the callback that is being called every time the gesture receives an update while it's active. diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.md b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.md new file mode 100644 index 0000000000..a99e15d95e --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.md @@ -0,0 +1,77 @@ +```ts +type GestureTouchEvent = { + handlerTag: number; + numberOfTouches: number; + state: ValueOf; + eventType: TouchEventType; + allTouches: TouchData[]; + changedTouches: TouchData[]; + pointerType: PointerType; +}; +``` + +### Callbacks common to all gestures: + +### onBegin + +```ts +onBegin: (event: HandlerData) => void +``` + +Set the callback that is being called when given gesture handler starts receiving touches. At the moment of this callback the handler is not yet in an active state and we don't know yet if it will recognize the gesture at all. + +### onActivate + +```ts +onActivate: (event: HandlerData) => void +``` + +Set the callback that is being called when the gesture is recognized by the handler and it transitions to the active state. + +### onDeactivate + +```ts +onDeactivate: (event: HandlerData) => void +``` + +Set the callback that is being called when the gesture that was recognized by the handler finishes. It will be called only if the handler was previously in the active state. + +### onFinalize + +```ts +onFinalize: (event: HandlerData) => void +``` + +Set the callback that is being called when the handler finalizes handling gesture - the gesture was recognized and has finished or it failed to recognize. + +### onTouchesDown + +```ts +onTouchesDown: (event: GestureTouchEvent) => void +``` + +Set the `onTouchesDown` callback which is called every time a finger is placed on the screen. + +### onTouchesMove + +```ts +onTouchesMove: (event: GestureTouchEvent) => void +``` + +Set the `onTouchesMove` callback which is called every time a finger is moved on the screen. + +### onTouchesUp + +```ts +onTouchesUp: (event: GestureTouchEvent) => void +``` + +Set the `onTouchesUp` callback which is called every time a finger is lifted from the screen. + +### onTouchesCancel + +```ts +onTouchesCancel: (event: GestureTouchEvent) => void +``` + +Set the `onTouchesCancel` callback which is called every time a finger stops being tracked, for example when the gesture finishes. diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md new file mode 100644 index 0000000000..1972798888 --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md @@ -0,0 +1,116 @@ +### Properties common to all gestures: + +### enabled + +```ts +enabled: boolean | SharedValue; +``` + +Indicates whether the given handler should be analyzing stream of touch events or not. +When set to `false` we can be sure that the handler's state will **never** become [`ACTIVE`](/docs/fundamentals/states-events#active). +If the value gets updated while the handler already started recognizing a gesture, then the handler's state it will immediately change to [`FAILED`](/docs/fundamentals/states-events#failed) or [`CANCELLED`](/docs/fundamentals/states-events#cancelled) (depending on its current state). +Default value is `true`. + +### shouldCancelWhenOutside + +```ts +shouldCancelWhenOutside: boolean | SharedValue; +``` + +When `true` the handler will [cancel](/docs/fundamentals/states-events#cancelled) or [fail](/docs/fundamentals/states-events#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. +Default value of this property is different depending on the handler type. +Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGesture`](/docs/gestures/long-press-gesture) and [`TapGesture`](/docs/gestures/tap-gesture) which default to `true`. + +### hitSlop + +```ts +hitSlop: HitSlop | SharedValue; +``` + +```ts +type HitSlop = + | number + | null + | undefined + | Partial< + Record< + 'left' | 'right' | 'top' | 'bottom' | 'vertical' | 'horizontal', + number + > + > + | Record<'width' | 'left', number> + | Record<'width' | 'right', number> + | Record<'height' | 'top', number> + | Record<'height' | 'bottom', number>; +``` + +This parameter enables control over what part of the connected view area can be used to [begin](/docs/fundamentals/states-events#began) recognizing the gesture. +When a negative number is provided the bounds of the view will reduce the area by the given number of points in each of the sides evenly. + +Instead you can pass an object to specify how each boundary side should be reduced by providing different number of points for `left`, `right`, `top` or `bottom` sides. +You can alternatively provide `horizontal` or `vertical` instead of specifying directly `left`, `right` or `top` and `bottom`. +Finally, the object can also take `width` and `height` attributes. +When `width` is set it is only allow to specify one of the sides `right` or `left`. +Similarly when `height` is provided only `top` or `bottom` can be set. +Specifying `width` or `height` is useful if we only want the gesture to activate on the edge of the view. In which case for example we can set `left: 0` and `width: 20` which would make it possible for the gesture to be recognize when started no more than 20 points from the left edge. + +**IMPORTANT:** Note that this parameter is primarily designed to reduce the area where gesture can activate. Hence it is only supported for all the values (except `width` and `height`) to be non positive (0 or lower). Although on Android it is supported for the values to also be positive and therefore allow to expand beyond view bounds but not further than the parent view bounds. To achieve this effect on both platforms you can use React Native's View [hitSlop](https://reactnative.dev/docs/view.html#hitslop) property. + +### testID + +```ts +testID: string; +``` + +Sets a `testID` property for gesture object, allowing for querying for it in tests. + +### `cancelsTouchesInView(value)` (**iOS only**) + +Accepts a boolean value. +When `true`, the gesture will cancel touches for native UI components (`UIButton`, `UISwitch`, etc) it's attached to when it becomes [`ACTIVE`](/docs/fundamentals/states-events#active). +Default value is `true`. + +### runOnJS + +```ts +runOnJS: boolean | SharedValue; +``` + +When `react-native-reanimated` is installed, the callbacks passed to the gestures are automatically workletized and run on the UI thread when called. This option allows for changing this behavior: when `true`, all the callbacks will be run on the JS thread instead of the UI thread, regardless of whether they are worklets or not. +Defaults to `false`. + +### simultaneousWith + +```ts +simultaneousWith: Gesture | Gesture[] +``` + +Adds a gesture that should be recognized simultaneously with this one. + +**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](/docs/fundamentals/gesture-composition). [`GestureDetector`](/docs/gestures/gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. + +### requireToFail + +```ts +requireToFail: Gesture | Gesture[] +``` + +Adds a relation requiring another gesture to fail, before this one can activate. + +### block + +```ts +block: Gesture | Gesture[] +``` + +Adds a relation that makes other gestures wait with activation until this gesture fails (or doesn't start at all). + +**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](/docs/fundamentals/gesture-composition).[`GestureDetector`](/docs/gestures/gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. + +### activeCursor + +```ts +activeCursor: ActiveCursor | SharedValue; +``` + +This parameter allows to specify which cursor should be used when gesture activates. Supports all [CSS cursor values](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/cursor#keyword) (e.g. `"grab"`, `"zoom-in"`). Default value is set to `"auto"`. diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-event-data.md b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-event-data.md new file mode 100644 index 0000000000..0ae1aa53a8 --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-event-data.md @@ -0,0 +1,27 @@ +### Event attributes common to all gestures: + +### numberOfPointers + +```ts +numberOfPointers: number; +``` + +Represents the number of pointers (fingers) currently placed on the screen. + +### pointerType + +```ts +pointerType: PointerType; +``` + +```ts +enum PointerType { + TOUCH, + STYLUS, + MOUSE, + KEY, // e.g. keyboard + OTHER, +} +``` + +Indicates the type of pointer device in use. diff --git a/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md new file mode 100644 index 0000000000..9a1f9780a8 --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md @@ -0,0 +1,347 @@ +--- +id: use-pan-gesture +title: Pan gesture +sidebar_label: Pan gesture +sidebar_position: 1 +--- + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import PanGestureBasic from '@site/static/examples/PanGestureBasic'; +import PanGestureBasicSrc from '!!raw-loader!@site/static/examples/PanGestureBasicSrc'; + +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +
+
+ +
+ } + src={PanGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +A continuous gesture that can recognize a panning (dragging) gesture and track its movement. + +The gesture [activates](/docs/fundamentals/states-events#active) when a finger is placed on the screen and moved some initial distance. + +Configurations such as a minimum initial distance, specific vertical or horizontal pan detection and [number of fingers](/docs/gestures/pan-gesture#minpointersvalue-number) required for activation (allowing for multifinger swipes) may be specified. + +Gesture callback can be used for continuous tracking of the pan gesture. It provides information about the gesture such as its XY translation from the starting point as well as its instantaneous velocity. + +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + usePanGesture, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + withTiming, + useAnimatedStyle, +} from 'react-native-reanimated'; + +export default function App() { + const position = useSharedValue(0); + + const panGesture = usePanGesture({ + onUpdate: (e) => { + position.value = e.translationX; + }, + onDeactivate: () => { + position.value = withTiming(0, { duration: 100 }); + }, + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ translateX: position.value }], + })); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Multi touch pan handling + +If your app relies on multi touch pan handling this section provides some information how the default behavior differs between the platform and how (if necessary) it can be unified. + +The difference in multi touch pan handling lies in the way how translation properties during the event are being calculated. +On iOS the default behavior when more than one finger is placed on the screen is to treat this situation as if only one pointer was placed in the center of mass (average position of all the pointers). +This applies also to many platform native components that handle touch even if not primarily interested in multi touch interactions like for example UIScrollView component. + +On Android, the default behavior for native components like scroll view, pager views or drawers is different and hence gesture defaults to that when it comes to pan handling. +The difference is that instead of treating the center of mass of all the fingers placed as a leading pointer it takes the latest placed finger as such. +This behavior can be changed on Android using [`averageTouches`](#averagetouchesvalue-boolean-android-only) flag. + +Note that on both Android and iOS when the additional finger is placed on the screen that translation prop is not affected even though the position of the pointer being tracked might have changed. +Therefore it is safe to rely on translation most of the time as it only reflects the movement that happens regardless of how many fingers are placed on the screen and if that number changes over time. +If you wish to track the "center of mass" virtual pointer and account for its changes when the number of finger changes you can use relative or absolute position provided in the event ([`x`](#x) and [`y`](#y) or [`absoluteX`](#absolutex) and [`absoluteY`](#absolutey)). + +## Config + +### Properties specific to `PanGesture`: + +### minDistance + +```ts +minDistance: number | SharedValue; +``` + +Minimum distance the finger (or multiple finger) need to travel before the gesture [activates](/docs/fundamentals/states-events#active). Expressed in points. + +### minPointers + +```ts +minPointers: number | SharedValue; +``` + +A number of fingers that is required to be placed before gesture can [activate](/docs/fundamentals/states-events#active). Should be a higher or equal to 0 integer. + +### maxPointers + +```ts +maxPointers: number | SharedValue; +``` + +When the given number of fingers is placed on the screen and gesture hasn't yet [activated](/docs/fundamentals/states-events#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. + +### activateAfterLongPress + +```ts +activateAfterLongPress: number | SharedValue; +``` + +Duration in milliseconds of the `LongPress` gesture before `Pan` is allowed to [activate](/docs/fundamentals/states-events#active). If the finger is moved during that period, the gesture will [fail](/docs/fundamentals/states-events#failed). Should be a higher or equal to 0 integer. Default value is 0, meaning no `LongPress` is required to [activate](/docs/fundamentals/states-events#active) the `Pan`. + +### activeOffsetX + +```ts +activeOffsetX: number | + SharedValue | + [number | SharedValue, number | SharedValue]; +``` + +Range along X axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. +If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. +If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. + +### activeOffsetY + +```ts +activeOffsetY: number | + SharedValue | + [number | SharedValue, number | SharedValue]; +``` + +Range along Y axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. +If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. +If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. + +### failOffsetY + +```ts +failOffsetY: number | + SharedValue | + [number | SharedValue, number | SharedValue]; +``` + +When the finger moves outside this range (in points) along Y axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. +If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. +If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. + +### failOffsetX + +```ts +failOffsetX: number | + SharedValue | + [number | SharedValue, number | SharedValue]; +``` + +When the finger moves outside this range (in points) along X axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. +If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. +If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. + +### averageTouches (Android only) + +```ts +averageTouches: boolean | SharedValue; +``` + +Android, by default, will calculate translation values based on the position of the leading pointer (the first one that was placed on the screen). This modifier allows that behavior to be changed to the one that is default on iOS - the averaged position of all active pointers will be used to calculate the translation values. + +### enableTrackpadTwoFingerGesture (iOS only) + +```ts +enableTrackpadTwoFingerGesture: boolean | SharedValue; +``` + +Enables two-finger gestures on supported devices, for example iPads with trackpads. If not enabled the gesture will require click + drag, with enableTrackpadTwoFingerGesture swiping with two fingers will also trigger the gesture. + +### mouseButton (Web & Android only) + +```ts +mouseButton: MouseButton | SharedValue; +``` + +```ts +enum MouseButton { + LEFT, + RIGHT, + MIDDLE, + BUTTON_4, + BUTTON_5, + ALL, +} +``` + +Allows users to choose which mouse button should handler respond to. Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`. + + + +## Callbacks + +```ts +type PanHandlerData = { + x: number; + y: number; + absoluteX: number; + absoluteY: number; + translationX: number; + translationY: number; + velocityX: number; + velocityY: number; + stylusData: StylusData; + changeX: number; + changeY: number; +}; +``` + + + + +## Event data + +### Event attributes specific to `PanGesture`: + +### translationX + +```ts +translationX: number; +``` + +Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. + +### translationY + +```ts +translationY: number; +``` + +Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. + +### velocityX + +```ts +velocityX: number; +``` + +Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. + +### velocityY + +```ts +velocityY: number; +``` + +Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. + +### x + +```ts +x: number; +``` + +X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). Expressed in point units. + +### y + +```ts +y: number; +``` + +Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). Expressed in point units. + +### absoluteX + +```ts +absoluteX: number; +``` + +X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. + +### absoluteY + +```ts +absoluteY: number; +``` + +Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. + +### stylusData + +```ts +stylusData: StylusData; +``` + +```ts +interface StylusData { + tiltX: number; + tiltY: number; + azimuthAngle: number; + altitudeAngle: number; + pressure: number; +} +``` + +Object that contains additional information about `stylus`. It consists of the following fields: + +- [`tiltX`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/tiltX) - angle in degrees between the Y-Z plane of the stylus and the screen. +- [`tiltY`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/tiltY) - angle in degrees between the X-Z plane of the stylus and the screen. +- [`altitudeAngle`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/altitudeAngle) - angle between stylus axis and the X-Y plane of a device screen. +- [`azimuthAngle`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/azimuthAngle) - angle between the Y-Z plane and the plane containing both the stylus axis and the Y axis. +- [`pressure`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/pressure) - indicates the normalized pressure of the stylus. + + From 203131ec0118f28838d3b3af67944214c7bd9fc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Wed, 10 Dec 2025 16:39:43 +0100 Subject: [PATCH 02/45] Finish (?) Pan --- .../docs/hooks/_shared/base-gesture-callbacks.md | 12 ------------ .../docs/hooks/_shared/base-gesture-config.md | 6 +++++- .../docs/hooks/use-pan-gesture.md | 4 ++-- 3 files changed, 7 insertions(+), 15 deletions(-) diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.md b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.md index a99e15d95e..e23a88715a 100644 --- a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.md +++ b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.md @@ -1,15 +1,3 @@ -```ts -type GestureTouchEvent = { - handlerTag: number; - numberOfTouches: number; - state: ValueOf; - eventType: TouchEventType; - allTouches: TouchData[]; - changedTouches: TouchData[]; - pointerType: PointerType; -}; -``` - ### Callbacks common to all gestures: ### onBegin diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md index 1972798888..3031ff6abb 100644 --- a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md +++ b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md @@ -64,7 +64,11 @@ testID: string; Sets a `testID` property for gesture object, allowing for querying for it in tests. -### `cancelsTouchesInView(value)` (**iOS only**) +### cancelsTouchesInView (**iOS only**) + +```ts +cancelsTouchesInView: boolean | SharedValue; +``` Accepts a boolean value. When `true`, the gesture will cancel touches for native UI components (`UIButton`, `UISwitch`, etc) it's attached to when it becomes [`ACTIVE`](/docs/fundamentals/states-events#active). diff --git a/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md index 9a1f9780a8..32389f316f 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md @@ -34,7 +34,7 @@ A continuous gesture that can recognize a panning (dragging) gesture and track i The gesture [activates](/docs/fundamentals/states-events#active) when a finger is placed on the screen and moved some initial distance. -Configurations such as a minimum initial distance, specific vertical or horizontal pan detection and [number of fingers](/docs/gestures/pan-gesture#minpointersvalue-number) required for activation (allowing for multifinger swipes) may be specified. +Configurations such as a [minimum initial distance](#mindistance), specific vertical or horizontal pan detection and [number of fingers](#minpointers) required for activation (allowing for multifinger swipes) may be specified. Gesture callback can be used for continuous tracking of the pan gesture. It provides information about the gesture such as its XY translation from the starting point as well as its instantaneous velocity. @@ -104,7 +104,7 @@ This applies also to many platform native components that handle touch even if n On Android, the default behavior for native components like scroll view, pager views or drawers is different and hence gesture defaults to that when it comes to pan handling. The difference is that instead of treating the center of mass of all the fingers placed as a leading pointer it takes the latest placed finger as such. -This behavior can be changed on Android using [`averageTouches`](#averagetouchesvalue-boolean-android-only) flag. +This behavior can be changed on Android using [`averageTouches`](#averagetouches-android-only) flag. Note that on both Android and iOS when the additional finger is placed on the screen that translation prop is not affected even though the position of the pointer being tracked might have changed. Therefore it is safe to rely on translation most of the time as it only reflects the movement that happens regardless of how many fingers are placed on the screen and if that number changes over time. From db99336c5f378ae21d20f9e9fe8c9ec91b5717b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Wed, 10 Dec 2025 17:10:34 +0100 Subject: [PATCH 03/45] Tap --- .../docs/hooks/_shared/base-gesture-config.md | 2 +- .../docs/hooks/use-pan-gesture.md | 8 +- .../docs/hooks/use-tap-gesture.md | 211 ++++++++++++++++++ 3 files changed, 219 insertions(+), 2 deletions(-) create mode 100644 packages/docs-gesture-handler/docs/hooks/use-tap-gesture.md diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md index 3031ff6abb..9484d5194d 100644 --- a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md +++ b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md @@ -19,7 +19,7 @@ shouldCancelWhenOutside: boolean | SharedValue; When `true` the handler will [cancel](/docs/fundamentals/states-events#cancelled) or [fail](/docs/fundamentals/states-events#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. Default value of this property is different depending on the handler type. -Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGesture`](/docs/gestures/long-press-gesture) and [`TapGesture`](/docs/gestures/tap-gesture) which default to `true`. +Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGesture`](/docs/hooks/use-long-press-gesture) and [`TapGesture`](/docs/hooks/use-tap-gesture) which default to `true`. ### hitSlop diff --git a/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md index 32389f316f..77790cf23d 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md @@ -34,10 +34,16 @@ A continuous gesture that can recognize a panning (dragging) gesture and track i The gesture [activates](/docs/fundamentals/states-events#active) when a finger is placed on the screen and moved some initial distance. -Configurations such as a [minimum initial distance](#mindistance), specific vertical or horizontal pan detection and [number of fingers](#minpointers) required for activation (allowing for multifinger swipes) may be specified. +Configurations such as a minimum initial distance, specific vertical or horizontal pan detection and number of fingers required for activation (allowing for multifinger swipes) may be specified. Gesture callback can be used for continuous tracking of the pan gesture. It provides information about the gesture such as its XY translation from the starting point as well as its instantaneous velocity. +
+ +
+ ## Example ```jsx diff --git a/packages/docs-gesture-handler/docs/hooks/use-tap-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-tap-gesture.md new file mode 100644 index 0000000000..3accd5f5df --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/use-tap-gesture.md @@ -0,0 +1,211 @@ +--- +id: use-tap-gesture +title: Tap gesture +sidebar_label: Tap gesture +sidebar_position: 2 +--- + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import TapGestureBasic from '@site/static/examples/TapGestureBasic'; +import TapGestureBasicSrc from '!!raw-loader!@site/static/examples/TapGestureBasic'; + +
+
+ +
+ } + src={TapGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; + +A discrete gesture that recognizes one or many taps. + +Tap gestures detect one or more fingers briefly touching the screen. +The fingers involved in these gestures must not move significantly from their initial touch positions. +The required number of taps and allowed distance from initial position may be configured. +For example, you might configure tap gesture recognizers to detect single taps, double taps, or triple taps. + +In order for a gesture to [activate](/docs/fundamentals/states-events#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDuration, and maxDelayMs (explained below) must be met. Immediately after the gesture [activates](/docs/fundamentals/states-events#active), it will [end](/docs/fundamentals/states-events#end). + +
+ +
+ +## Example + +```jsx +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useTapGesture, +} from 'react-native-gesture-handler'; + +export default function App() { + const singleTap = useTapGesture({ + maxDuration: 250, + onActivate: () => { + console.log('Single tap!'); + }, + }); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Config + +### Properties specific to `TapGesture`: + +### minPointers + +```ts +minPointers: number | SharedValue; +``` + +Minimum number of pointers (fingers) required to be placed before the gesture [activates](/docs/fundamentals/states-events#active). Should be a positive integer. The default value is 1. + +### maxDuration + +```ts +maxDuration: number | SharedValue; +``` + +Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. + +### maxDelay + +```ts +maxDelay: number | SharedValue; +``` + +Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. + +### numberOfTaps + +```ts +numberOfTaps: number | SharedValue; +``` + +Number of tap gestures required to [activate](/docs/fundamentals/states-events#active) the gesture. The default value is 1. + +### maxDeltaX + +```ts +maxDeltaX: number | SharedValue; +``` + +Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture. If the finger travels further than the defined distance along the X axis and the gesture hasn't yet [activated](/docs/fundamentals/states-events#active), it will fail to recognize the gesture. + +### maxDeltaY + +```ts +maxDeltaY: number | SharedValue; +``` + +Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture. If the finger travels further than the defined distance along the Y axis and the gesture hasn't yet [activated](/docs/fundamentals/states-events#active), it will fail to recognize the gesture. + +### maxDistance + +```ts +maxDistance: number | SharedValue; +``` + +Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](/docs/fundamentals/states-events#active), it will fail to recognize the gesture. + +### mouseButton (Web & Android only) + +```ts +mouseButton: MouseButton | SharedValue; +``` + +```ts +enum MouseButton { + LEFT, + RIGHT, + MIDDLE, + BUTTON_4, + BUTTON_5, + ALL, +} +``` + +Allows users to choose which mouse button should handler respond to. Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`. + + + +## Callbacks + + + +## Event data + +### Event attributes specific to `TapGesture`: + +### x + +```ts +x: number; +``` + +X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). + +### y + +```ts +y: number; +``` + +Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). + +### absoluteX + +```ts +absoluteX: number; +``` + +X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector) can be transformed as an effect of the gesture. + +### absoluteY + +```ts +absoluteY: number; +``` + +Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector) can be transformed as an effect of the gesture. + + From f01bd6661ec3f374d3ee27a173ecc18496b3f702 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Wed, 10 Dec 2025 17:19:13 +0100 Subject: [PATCH 04/45] Long press --- .../hooks/_shared/base-gesture-event-data.md | 2 +- .../docs/hooks/use-long-press-gesture.md | 175 ++++++++++++++++++ 2 files changed, 176 insertions(+), 1 deletion(-) create mode 100644 packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.md diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-event-data.md b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-event-data.md index 0ae1aa53a8..86fb0115ff 100644 --- a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-event-data.md +++ b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-event-data.md @@ -19,7 +19,7 @@ enum PointerType { TOUCH, STYLUS, MOUSE, - KEY, // e.g. keyboard + KEY, OTHER, } ``` diff --git a/packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.md new file mode 100644 index 0000000000..501ef10353 --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.md @@ -0,0 +1,175 @@ +--- +id: use-long-press-gesture +title: Long press gesture +sidebar_label: Long press gesture +sidebar_position: 3 +--- + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import LongPressGestureBasic from '@site/static/examples/LongPressGestureBasic'; +import LongPressGestureBasicSrc from '!!raw-loader!@site/static/examples/LongPressGestureBasic'; + +
+
+ +
+ } + src={LongPressGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; + +A discrete gesture that activates when the corresponding view is pressed for a sufficiently long time. +This gesture's state will turn into [END](/docs/fundamentals/states-events#end) immediately after the finger is released. +The gesture will fail to recognize a touch event if the finger is lifted before the minimum required time or if the finger is moved further than the allowable distance. + +
+ +
+ +## Example + +```jsx +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useLongPressGesture, +} from 'react-native-gesture-handler'; + +export default function App() { + const longPressGesture = useLongPressGesture({ + onDeactivate: (e, success) => { + if (success) { + console.log(`Long pressed for ${e.duration} ms!`); + } + }, + }); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Config + +### Properties specific to `LongPressGesture`: + +### minDuration + +```ts +minDuration: number | SharedValue; +``` + +Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. + +### maxDistance + +```ts +maxDistance: number | SharedValue; +``` + +Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](/docs/fundamentals/states-events#active), it will fail to recognize the gesture. The default value is 10. + +### mouseButton (Web & Android only) + +```ts +mouseButton: MouseButton | SharedValue; +``` + +```ts +enum MouseButton { + LEFT, + RIGHT, + MIDDLE, + BUTTON_4, + BUTTON_5, + ALL, +} +``` + +Allows users to choose which mouse button should handler respond to. Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`. + + + +## Callbacks + + + +## Event data + +### Event attributes specific to `LongPressGesture`: + +### x + +```ts +x: number; +``` + +X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). + +### y + +```ts +y: number; +``` + +Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). + +### absoluteX + +```ts +absoluteX: number; +``` + +X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector) can be transformed as an effect of the gesture. + +### absoluteY + +```ts +absoluteY: number; +``` + +Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector) can be transformed as an effect of the gesture. + +### duration + +```ts +duration: number; +``` + +Duration of the long press (time since the start of the gesture), expressed in milliseconds. + + From 5490439ef7366eecf7d6707d9580a4e3f4f75018 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Wed, 10 Dec 2025 17:39:39 +0100 Subject: [PATCH 05/45] Rotation --- .../_shared/base-continuous-gesture-config.md | 9 ++ .../docs/hooks/use-long-press-gesture.md | 8 +- .../docs/hooks/use-pan-gesture.md | 2 + .../docs/hooks/use-rotation-gesture.md | 152 ++++++++++++++++++ .../docs/hooks/use-tap-gesture.md | 8 +- 5 files changed, 171 insertions(+), 8 deletions(-) create mode 100644 packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-config.md create mode 100644 packages/docs-gesture-handler/docs/hooks/use-rotation-gesture.md diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-config.md b/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-config.md new file mode 100644 index 0000000000..af148874b5 --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-config.md @@ -0,0 +1,9 @@ +### Properties common to all continuous gestures: + +### manualActivation + +```ts +manualActivation: boolean | SharedValue; +``` + +When `true` the handler will not activate by itself even if its activation criteria are met. Instead you can manipulate its state using [state manager](/docs/gestures/state-manager/). diff --git a/packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.md index 501ef10353..f61e8d6c5e 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.md @@ -26,8 +26,8 @@ import LongPressGestureBasicSrc from '!!raw-loader!@site/static/examples/LongPre import BaseEventData from './\_shared/base-gesture-event-data.md'; -import BaseEventConfig from './\_shared/base-gesture-config.md'; -import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; A discrete gesture that activates when the corresponding view is pressed for a sufficiently long time. This gesture's state will turn into [END](/docs/fundamentals/states-events#end) immediately after the finger is released. @@ -122,11 +122,11 @@ enum MouseButton { Allows users to choose which mouse button should handler respond to. Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`. - + ## Callbacks - + ## Event data diff --git a/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md index 77790cf23d..4af376640e 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md @@ -14,6 +14,7 @@ import PanGestureBasicSrc from '!!raw-loader!@site/static/examples/PanGestureBas import BaseEventData from './\_shared/base-gesture-event-data.md'; import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseContinuousGestureConfig from './\_shared/base-continuous-gesture-config.md'; import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; @@ -236,6 +237,7 @@ enum MouseButton { Allows users to choose which mouse button should handler respond to. Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`. + ## Callbacks diff --git a/packages/docs-gesture-handler/docs/hooks/use-rotation-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-rotation-gesture.md new file mode 100644 index 0000000000..dc7b338d8c --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/use-rotation-gesture.md @@ -0,0 +1,152 @@ +--- +id: use-rotation-gesture +title: Rotation gesture +sidebar_label: Rotation gesture +sidebar_position: 4 +--- + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import RotationGestureBasic from '@site/static/examples/RotationGestureBasic'; +import RotationGestureBasicSrc from '!!raw-loader!@site/static/examples/RotationGestureBasicSrc'; + +
+
+ +
+ } + src={RotationGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseContinuousGestureConfig from './\_shared/base-continuous-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +A continuous gesture that can recognize a rotation gesture and track its movement. + +The gesture [activates](/docs/fundamentals/states-events#active) when fingers are placed on the screen and change position in a proper way. + +Gesture callback can be used for continuous tracking of the rotation gesture. It provides information about the gesture such as the amount rotated, the focal point of the rotation (anchor), and its instantaneous velocity. + +
+ +
+ +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useRotationGesture, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, +} from 'react-native-reanimated'; + +export default function App() { + const rotation = useSharedValue(1); + const savedRotation = useSharedValue(1); + + const rotationGesture = useRotationGesture({ + onUpdate: (e) => { + rotation.value = savedRotation.value + e.rotation; + }, + onDeactivate: () => { + savedRotation.value = rotation.value; + }, + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ rotateZ: `${(rotation.value / Math.PI) * 180}deg` }], + })); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Remarks + +- When implementing rotation based on `anchor` point, make sure to use it after gesture has activated, i.e. in `onActivate` or `onUpdate` callbacks. Using it in `onBegin` may lead to unexpected behavior. + +## Config + + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `RotationGesture`: + +### rotation + +```ts +rotation: number; +``` + +Amount rotated, expressed in radians, from the gesture's focal point (anchor). + +### velocity + +```ts +velocity: number; +``` + +Instantaneous velocity, expressed in point units per second, of the gesture. + +### anchorX + +```ts +anchorX: number; +``` + +X coordinate, expressed in points, of the gesture's central focal point (anchor). + +### anchorY + +```ts +anchorY: number; +``` + +Y coordinate, expressed in points, of the gesture's central focal point (anchor). + + diff --git a/packages/docs-gesture-handler/docs/hooks/use-tap-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-tap-gesture.md index 3accd5f5df..3d845de681 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-tap-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-tap-gesture.md @@ -26,8 +26,8 @@ import TapGestureBasicSrc from '!!raw-loader!@site/static/examples/TapGestureBas import BaseEventData from './\_shared/base-gesture-event-data.md'; -import BaseEventConfig from './\_shared/base-gesture-config.md'; -import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; A discrete gesture that recognizes one or many taps. @@ -166,11 +166,11 @@ enum MouseButton { Allows users to choose which mouse button should handler respond to. Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`. - + ## Callbacks - + ## Event data From ded8083c6ad804d86796d9cda0460b627e9b201b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Wed, 10 Dec 2025 17:47:54 +0100 Subject: [PATCH 06/45] Pinch --- .../docs/hooks/use-pinch-gesture.md | 155 ++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 packages/docs-gesture-handler/docs/hooks/use-pinch-gesture.md diff --git a/packages/docs-gesture-handler/docs/hooks/use-pinch-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-pinch-gesture.md new file mode 100644 index 0000000000..3e88a006e9 --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/use-pinch-gesture.md @@ -0,0 +1,155 @@ +--- +id: use-pinch-gesture +title: Pinch gesture +sidebar_label: Pinch gesture +sidebar_position: 5 +--- + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import PinchGestureBasic from '@site/static/examples/PinchGestureBasic'; +import PinchGestureBasicSrc from '!!raw-loader!@site/static/examples/PinchGestureBasicSrc'; + +
+
+ +
+ } + src={PinchGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseContinuousGestureConfig from './\_shared/base-continuous-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +A continuous gesture that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. +The gesture [activates](/docs/fundamentals/states-events#active) when fingers are placed on the screen and change their position. +Gesture callback can be used for continuous tracking of the pinch gesture. It provides information about velocity, anchor (focal) point of gesture and scale. + +The distance between the fingers is reported as a scale factor. At the beginning of the gesture, the scale factor is 1.0. As the distance between the two fingers increases, the scale factor increases proportionally. +Similarly, the scale factor decreases as the distance between the fingers decreases. +Pinch gestures are used most commonly to change the size of objects or content onscreen. +For example, map views use pinch gestures to change the zoom level of the map. + +
+ +
+ +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + usePinchGesture, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, +} from 'react-native-reanimated'; + +export default function App() { + const scale = useSharedValue(1); + const savedScale = useSharedValue(1); + + const pinchGesture = usePinchGesture({ + onUpdate: (e) => { + scale.value = savedScale.value * e.scale; + }, + onDeactivate: () => { + savedScale.value = scale.value; + }, + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ scale: scale.value }], + })); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Remarks + +- When implementing pinch based on `focal` point, make sure to use it after gesture has activated, i.e. in `onActivate` or `onUpdate` callbacks. Using it in `onBegin` may lead to unexpected behavior. + +## Config + + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `PinchGesture`: + +### scale + +```ts +scale: number; +``` + +The scale factor relative to the points of the two touches in screen coordinates. + +### velocity + +```ts +velocity: number; +``` + +Velocity of the pan gesture the current moment. The value is expressed in scale factor per second. + +### `focalX` + +```ts +focalX: number; +``` + +Position expressed in points along X axis of center anchor point of gesture + +### `focalY` + +```ts +focalY: number; +``` + +Position expressed in points along Y axis of center anchor point of gesture + + From e38591c8b975a2593b79a25fc898a35f6274714e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Wed, 10 Dec 2025 18:06:42 +0100 Subject: [PATCH 07/45] Fling --- .../docs/hooks/use-fling-gesture.md | 189 ++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 packages/docs-gesture-handler/docs/hooks/use-fling-gesture.md diff --git a/packages/docs-gesture-handler/docs/hooks/use-fling-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-fling-gesture.md new file mode 100644 index 0000000000..85a16d33fe --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/use-fling-gesture.md @@ -0,0 +1,189 @@ +--- +id: use-fling-gesture +title: Fling gesture +sidebar_label: Fling gesture +sidebar_position: 6 +--- + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import FlingGestureBasic from '@site/static/examples/FlingGestureBasic'; +import FlingGestureBasicSrc from '!!raw-loader!@site/static/examples/FlingGestureBasicSrc'; + +
+
+ +
+ } + src={FlingGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; + +A discrete gesture that activates when the movement is sufficiently long and fast. +Gesture gets [ACTIVE](/docs/fundamentals/states-events#active) when movement is sufficiently long and it does not take too much time. +When gesture gets activated it will turn into [END](/docs/fundamentals/states-events#end) state when finger is released. +The gesture will fail to recognize if the finger is lifted before being activated. + +
+ +
+ +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + Directions, + useFlingGesture, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, + withTiming, +} from 'react-native-reanimated'; + +export default function App() { + const position = useSharedValue(0); + + const flingGesture = useFlingGesture({ + direction: Directions.RIGHT, + onActivate: () => { + position.value = withTiming(position.value + 10, { duration: 100 }); + }, + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ translateX: position.value }], + })); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Config + +### Properties specific to `FlingGesture`: + +### direction + +```ts +direction: Directions | SharedValue; +``` + +Expressed allowed direction of movement. Expected values are exported as constants in the `Directions` object. It's possible to pass one or many directions in one parameter: + +```js +import { Directions } from 'react-native-gesture-handler'; + +// Single direction +fling.direction(Directions.DOWN); + +// Combined directions +fling.direction(Directions.RIGHT | Directions.LEFT); +``` + +### numberOfPointers + +```ts +numberOfPointers: number | SharedValue; +``` + +Determine exact number of points required to handle the fling gesture. + +### mouseButton (Web & Android only) + +```ts +mouseButton: MouseButton | SharedValue; +``` + +```ts +enum MouseButton { + LEFT, + RIGHT, + MIDDLE, + BUTTON_4, + BUTTON_5, + ALL, +} +``` + +Allows users to choose which mouse button should handler respond to. Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`. + + + +## Callbacks + + + +## Event data + +### Event attributes specific to `FlingGesture`: + +### x + +```ts +x: number; +``` + +X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. + +### y + +```ts +y: number; +``` + +Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. + +### absoluteX + +```ts +absoluteX: number; +``` + +X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. + +### absoluteY + +```ts +absoluteY: number; +``` + +Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. + + From f338fa7b5ff4d707de9330c809c2cffa5d17c6b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Wed, 10 Dec 2025 18:23:29 +0100 Subject: [PATCH 08/45] Hover --- .../docs/hooks/use-hover-gesture.md | 172 ++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 packages/docs-gesture-handler/docs/hooks/use-hover-gesture.md diff --git a/packages/docs-gesture-handler/docs/hooks/use-hover-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-hover-gesture.md new file mode 100644 index 0000000000..09a4683514 --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/use-hover-gesture.md @@ -0,0 +1,172 @@ +--- +id: use-hover-gesture +title: Hover gesture +sidebar_label: Hover gesture +sidebar_position: 7 +--- + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import HoverGestureBasic from '@site/static/examples/HoverGestureBasic'; +import HoverGestureBasicSrc from '!!raw-loader!@site/static/examples/HoverGestureBasic'; + +
+
+ +
+ } + src={HoverGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +A continuous gesture that can recognize hovering above the view it's attached to. The hover effect may be activated by moving a mouse or a stylus over the view. + +On iOS additional visual effects may be configured. + +
+ +
+ +## Reference + +```jsx +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useHoverGesture, +} from 'react-native-gesture-handler'; + +export default function App() { + const hoverGesture = useHoverGesture({}); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Remarks + +- Don't rely on `Hover` gesture to continue after the mouse button is clicked or the stylus touches the screen. If you want to handle both cases, [compose](/docs/fundamentals/gesture-composition) it with [`Pan` gesture](/docs/gestures/pan-gesture). + +## Config + +### Properties specific to `HoverGesture`: + +### effect (iOS only) + +```ts +effect: HoverEffect | SharedValue; +``` + +```ts +enum HoverEffect { + NONE = 0, + LIFT = 1, + HIGHLIGHT = 2, +} +``` + +Visual effect applied to the view while the view is hovered. Defaults to `HoverEffect.None` + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `HoverGesture`: + +### x + +```ts +x: number; +``` + +X coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). Expressed in point units. + +### y + +```ts +y: number; +``` + +Y coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). Expressed in point units. + +### absoluteX + +```ts +absoluteX: number; +``` + +X coordinate of the current position of the pointer relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. + +### absoluteY + +```ts +absoluteY: number; +``` + +Y coordinate of the current position of the pointer relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. + +### stylusData + +```ts +stylusData: StylusData; +``` + +```ts +interface StylusData { + tiltX: number; + tiltY: number; + azimuthAngle: number; + altitudeAngle: number; + pressure: number; +} +``` + +Object that contains additional information about `stylus`. It consists of the following fields: + +- [`tiltX`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/tiltX) - angle in degrees between the Y-Z plane of the stylus and the screen. +- [`tiltY`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/tiltY) - angle in degrees between the X-Z plane of the stylus and the screen. +- [`altitudeAngle`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/altitudeAngle) - angle between stylus axis and the X-Y plane of a device screen. +- [`azimuthAngle`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/azimuthAngle) - angle between the Y-Z plane and the plane containing both the stylus axis and the Y axis. +- [`pressure`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/pressure) - indicates the normalized pressure of the stylus. + + From 11c91a75e0126a6a957a61389dcc8c50a22e8bb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Wed, 10 Dec 2025 18:47:02 +0100 Subject: [PATCH 09/45] Native --- .../docs/hooks/use-native-gesture.md | 125 ++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 packages/docs-gesture-handler/docs/hooks/use-native-gesture.md diff --git a/packages/docs-gesture-handler/docs/hooks/use-native-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-native-gesture.md new file mode 100644 index 0000000000..b62abd37f1 --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/use-native-gesture.md @@ -0,0 +1,125 @@ +--- +id: use-native-gesture +title: Native gesture +sidebar_label: Native gesture +sidebar_position: 8 +--- + +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +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. + +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 { View, ScrollView } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useNativeGesture, + usePanGesture, + NativeGesture, +} from 'react-native-gesture-handler'; + +const COLORS = ['red', 'green', 'blue', 'purple', 'orange', 'cyan']; + +export default function App() { + const nativeGesture = useNativeGesture({}); + + return ( + + + + + {COLORS.map((color) => ( + + ))} + + + + + ); +} + +type RectangleProps = { + color: string; + scrollGesture: NativeGesture; +}; + +function Rectangle({ color, scrollGesture }: RectangleProps) { + const pan = usePanGesture({ + block: 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 (**Android only**) + +```ts +shouldActivateOnStart: boolean | SharedValue; +``` + +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 + +```ts +disallowInterruption: boolean | SharedValue; +``` + +When `true`, cancels all other gesture handlers when changes its state to [`ACTIVE`](/docs/fundamentals/states-events#active). + + + +## Callbacks + + + +## Event data + +### Event attributes specific to `NativeGesture`: + +### pointerInside + +```ts +pointerInside: boolean; +``` + +`true` if gesture was performed inside of containing view, `false` otherwise. + + From 37d7438e5d5141a24bd5085e29d3c9d2cd33ecdd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Wed, 10 Dec 2025 18:51:04 +0100 Subject: [PATCH 10/45] Manual --- .../docs/hooks/use-manual-gesture.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 packages/docs-gesture-handler/docs/hooks/use-manual-gesture.md diff --git a/packages/docs-gesture-handler/docs/hooks/use-manual-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-manual-gesture.md new file mode 100644 index 0000000000..6729e79bca --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/use-manual-gesture.md @@ -0,0 +1,49 @@ +--- +id: use-manual-gesture +title: Manual gesture +sidebar_label: Manual gesture +sidebar_position: 9 +--- + +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +A plain gesture that has no specific activation criteria nor event data set. Its state has to be controlled manually using a [state manager](/docs/gestures/state-manager). It will not fail when all the pointers are lifted from the screen. + +## Reference + +```jsx +import { + GestureDetector, + GestureHandlerRootView, + useManualGesture, +} from 'react-native-gesture-handler'; +import Animated from 'react-native-reanimated'; + +export default function App() { + const manualGesture = useManualGesture({}); + + return ( + + + + + + ); +} +``` + +## Config + + + +## Callbacks + + + + +## Event data + + From a93970a397e5908204f84e95d9c1cd1577ac71f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Wed, 10 Dec 2025 19:01:33 +0100 Subject: [PATCH 11/45] Fix path --- packages/docs-gesture-handler/docs/hooks/use-fling-gesture.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/docs-gesture-handler/docs/hooks/use-fling-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-fling-gesture.md index 85a16d33fe..9a38c32113 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-fling-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-fling-gesture.md @@ -160,7 +160,7 @@ Allows users to choose which mouse button should handler respond to. Arguments c x: number; ``` -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. +X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](../gestures/gesture-detector.md). Expressed in point units. ### y @@ -168,7 +168,7 @@ X coordinate of the current position of the pointer (finger or a leading pointer y: number; ``` -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. +Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](../gestures/gesture-detector.md). Expressed in point units. ### absoluteX From d23e66b0f41a0f9b545e9de3f5aba142060c5083 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Wed, 10 Dec 2025 19:21:45 +0100 Subject: [PATCH 12/45] Remove cache from workflow --- .github/workflows/docs-check.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml index 109cbec317..064990d766 100644 --- a/.github/workflows/docs-check.yml +++ b/.github/workflows/docs-check.yml @@ -25,7 +25,6 @@ jobs: uses: actions/setup-node@v6 with: node-version: 24 - cache: yarn - name: Install node dependencies working-directory: ${{ env.WORKING_DIRECTORY }} From 5c0b717c75396430aee51d8b4dd710c9c68fa1d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Thu, 11 Dec 2025 16:36:41 +0100 Subject: [PATCH 13/45] composition --- .../docs/hooks/gesture-composition.md | 476 ++++++++++++++++++ 1 file changed, 476 insertions(+) create mode 100644 packages/docs-gesture-handler/docs/hooks/gesture-composition.md diff --git a/packages/docs-gesture-handler/docs/hooks/gesture-composition.md b/packages/docs-gesture-handler/docs/hooks/gesture-composition.md new file mode 100644 index 0000000000..0026681bec --- /dev/null +++ b/packages/docs-gesture-handler/docs/hooks/gesture-composition.md @@ -0,0 +1,476 @@ +--- +id: gesture-composition +title: Gesture composition & interactions +sidebar_label: Gesture composition & interactions +sidebar_position: 10 +--- + +RNGH3 provides simple way to set up interactions between gestures by using dedicated hooks and config properties. + +## Composition hooks + +### useCompetingGestures + +Only one of the provided gestures can become active at the same time. The first gesture to become active will cancel the rest of the gestures. It accepts variable number of arguments. +It is the equivalent to having more than one gesture handler without defining `simultaneousWith`, `requireTofail` and `block` props. + +For example, lets say that you have a component that you want to make draggable but you also want to show additional options on long press. Presumably you would not want the component to move after the long press activates. You can accomplish this using `useCompetingGestures`: + +> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). + +```js +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + usePanGesture, + useLongPressGesture, + GestureHandlerRootView, + useCompetingGestures, +} from 'react-native-gesture-handler'; + +export default function App() { + const panGesture = usePanGesture({ + onUpdate: () => { + console.log('Pan'); + }, + }); + const longPressGesture = useLongPressGesture({ + onDeactivate: (_, success) => { + if (success) { + console.log('Long Press'); + } + }, + }); + + const gesture = useCompetingGestures(panGesture, longPressGesture); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +### useSimultaneousGestures + +All of the provided gestures can activate at the same time. Activation of one will not cancel the other. +It is the equivalent to having some gesture handlers, each with `simultaneousWith` prop set to the other handlers. + +For example, if you want to make a gallery app, you might want user to be able to zoom, rotate and pan around photos. You can do it with `useSimultaneousGestures`: + +> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). + +```js +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + usePanGesture, + usePinchGesture, + useRotationGesture, + useSimultaneousGestures, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, +} from 'react-native-reanimated'; + +export default function App() { + const offset = useSharedValue({ x: 0, y: 0 }); + const start = useSharedValue({ x: 0, y: 0 }); + + const scale = useSharedValue(1); + const savedScale = useSharedValue(1); + const rotation = useSharedValue(0); + const savedRotation = useSharedValue(0); + + const animatedStyles = useAnimatedStyle(() => { + return { + transform: [ + { translateX: offset.value.x }, + { translateY: offset.value.y }, + { scale: scale.value }, + { rotateZ: `${rotation.value}rad` }, + ], + }; + }); + + const dragGesture = usePanGesture({ + averageTouches: true, + onUpdate: (e) => { + offset.value = { + x: e.translationX + start.value.x, + y: e.translationY + start.value.y, + }; + }, + onDeactivate: () => { + start.value = { + x: offset.value.x, + y: offset.value.y, + }; + }, + }); + + const zoomGesture = usePinchGesture({ + onUpdate: (e) => { + scale.value = savedScale.value * e.scale; + }, + onDeactivate: () => { + savedScale.value = scale.value; + }, + }); + + const rotationGesture = useRotationGesture({ + onUpdate: (e) => { + rotation.value = savedRotation.value + e.rotation; + }, + onDeactivate: () => { + savedRotation.value = rotation.value; + }, + }); + + const composedGesture = useSimultaneousGestures( + dragGesture, + zoomGesture, + rotationGesture + ); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + width: 100, + height: 100, + backgroundColor: 'blue', + }, +}); +``` + +### useExclusiveGestures + +Only one of the provided gestures can become active, with the first one having a higher priority than the second one (if both gestures are still possible, the second one will wait for the first one to fail before it activates), second one having a higher priority than the third one, and so on. +It is equivalent to having some gesture handlers where the second one has the `requireToFail` prop set to the first handler, third one has the `requireToFail` prop set to the first and the second one, and so on. + +For example, if you want to make a component that responds to single tap as well as to a double tap, you can accomplish that using `useExclusiveGestures`: + +> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). + +```js +import { StyleSheet, View } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useTapGesture, + useExclusiveGestures, +} from 'react-native-gesture-handler'; + +export default function App() { + const singleTap = useTapGesture({ + onDeactivate: (_, success) => { + if (success) { + console.log('Single tap!'); + } + }, + }); + + const doubleTap = useTapGesture({ + numberOfTaps: 2, + onDeactivate: (_, success) => { + if (success) { + console.log('Double tap!'); + } + }, + }); + + const taps = useExclusiveGestures(doubleTap, singleTap); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + width: 100, + height: 100, + backgroundColor: 'plum', + }, +}); +``` + +## Cross-component interactions + +You may have noticed that gesture composition described above requires you to mount all of the composed gestures under a single `GestureDetector`, effectively attaching them to the same underlying component. You can customize how gestures interact with each other across multiple components in a couple of ways: + +### requireToFail + +`requireToFail` allows to delay activation of the handler until all handlers passed as arguments to this method fail (or don't begin at all). + +For example, you may want to have two nested components, both of them can be tapped by the user to trigger different actions: outer view requires one tap, but the inner one requires 2 taps. If you don't want the first tap on the inner view to activate the outer handler, you must make the outer gesture wait until the inner one fails: + +```jsx +import React from 'react'; +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useTapGesture, +} from 'react-native-gesture-handler'; + +export default function Example() { + const innerTap = useTapGesture({ + numberOfTaps: 2, + onDeactivate: (_, success) => { + if (success) { + console.log('inner tap'); + } + }, + }); + + const outerTap = useTapGesture({ + onDeactivate: (_, success) => { + if (success) { + console.log('outer tap'); + } + }, + requireToFail: innerTap, + }); + + return ( + + + + + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'center', + }, + outer: { + width: 250, + height: 250, + backgroundColor: 'lightblue', + }, + inner: { + width: 100, + height: 100, + backgroundColor: 'blue', + alignSelf: 'center', + }, +}); +``` + +### block + +`block` works similarly to `requireToFail` but the direction of the relation is reversed - instead of being one-to-many relation, it's many-to-one. It's especially useful for making lists where the `ScrollView` component needs to wait for every gesture underneath it. All that's required to do is to pass a ref, for example: + +```jsx +import React, { useState } from 'react'; +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + ScrollView, + NativeGesture, + usePinchGesture, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, + withTiming, +} from 'react-native-reanimated'; + +const ITEMS = ['red', 'green', 'blue', 'yellow']; + +export default function Example() { + const [scrollGesture, setScrollGesture] = useState( + null + ); + + return ( + + { + if (!scrollGesture || scrollGesture.tag !== gesture.tag) { + setScrollGesture(gesture); + } + }}> + {ITEMS.map((item) => ( + + ))} + + + ); +} + +type ItemProps = { + backgroundColor: string; + scrollGesture: NativeGesture | null; +}; + +function Item({ backgroundColor, scrollGesture }: ItemProps) { + const scale = useSharedValue(1); + const zIndex = useSharedValue(1); + + const pinch = usePinchGesture({ + onBegin: () => { + zIndex.value = 100; + }, + onUpdate: (e) => { + scale.value *= e.scaleChange; + }, + onFinalize: () => { + scale.value = withTiming(1, undefined, (finished) => { + if (finished) { + zIndex.value = 1; + } + }); + }, + block: scrollGesture ?? undefined, + }); + + const animatedStyles = useAnimatedStyle(() => ({ + transform: [{ scale: scale.value }], + zIndex: zIndex.value, + })); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + }, + item: { + flex: 1, + aspectRatio: 1, + }, +}); +``` + +### simultaneousWith + +`simultaneousWith` allows gestures across different components to be recognized simultaneously. For example, you may want to have two nested views, both with tap gesture attached. Both of them require one tap, but tapping the inner one should also activate the gesture attached to the outer view: + +```jsx +import React from 'react'; +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useTapGesture, +} from 'react-native-gesture-handler'; + +export default function Example() { + const innerTap = useTapGesture({ + onDeactivate: (_, success) => { + if (success) { + console.log('inner tap'); + } + }, + }); + + const outerTap = useTapGesture({ + onDeactivate: (_, success) => { + if (success) { + console.log('outer tap'); + } + }, + simultaneousWith: innerTap, + }); + + return ( + + + + + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'center', + }, + outer: { + width: 250, + height: 250, + backgroundColor: 'lightblue', + }, + inner: { + width: 100, + height: 100, + backgroundColor: 'blue', + alignSelf: 'center', + }, +}); +``` From f29394983cdeccceb210426ec9fec85f779e748b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Mon, 15 Dec 2025 11:39:45 +0100 Subject: [PATCH 14/45] Remove PanHandlerData --- .../docs/hooks/use-pan-gesture.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md index 4af376640e..c6b21e5305 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md @@ -241,22 +241,6 @@ Allows users to choose which mouse button should handler respond to. Arguments c ## Callbacks -```ts -type PanHandlerData = { - x: number; - y: number; - absoluteX: number; - absoluteY: number; - translationX: number; - translationY: number; - velocityX: number; - velocityY: number; - stylusData: StylusData; - changeX: number; - changeY: number; -}; -``` - From 34a93a5200cced75b40b1b2f9621ab1e917ec00f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Mon, 15 Dec 2025 13:47:08 +0100 Subject: [PATCH 15/45] Use correct HandlerData --- ... => base-continuous-gesture-callbacks.mdx} | 10 ++++-- ...allbacks.md => base-gesture-callbacks.mdx} | 34 ++++++++++++------- ...fling-gesture.md => use-fling-gesture.mdx} | 4 +-- ...hover-gesture.md => use-hover-gesture.mdx} | 8 ++--- ...-gesture.md => use-long-press-gesture.mdx} | 4 +-- ...nual-gesture.md => use-manual-gesture.mdx} | 8 ++--- ...tive-gesture.md => use-native-gesture.mdx} | 6 ++-- ...use-pan-gesture.md => use-pan-gesture.mdx} | 8 ++--- ...pinch-gesture.md => use-pinch-gesture.mdx} | 8 ++--- ...on-gesture.md => use-rotation-gesture.mdx} | 8 ++--- ...use-tap-gesture.md => use-tap-gesture.mdx} | 4 +-- 11 files changed, 58 insertions(+), 44 deletions(-) rename packages/docs-gesture-handler/docs/hooks/_shared/{base-continuous-gesture-callbacks.md => base-continuous-gesture-callbacks.mdx} (50%) rename packages/docs-gesture-handler/docs/hooks/_shared/{base-gesture-callbacks.md => base-gesture-callbacks.mdx} (73%) rename packages/docs-gesture-handler/docs/hooks/{use-fling-gesture.md => use-fling-gesture.mdx} (99%) rename packages/docs-gesture-handler/docs/hooks/{use-hover-gesture.md => use-hover-gesture.mdx} (97%) rename packages/docs-gesture-handler/docs/hooks/{use-long-press-gesture.md => use-long-press-gesture.mdx} (98%) rename packages/docs-gesture-handler/docs/hooks/{use-manual-gesture.md => use-manual-gesture.mdx} (89%) rename packages/docs-gesture-handler/docs/hooks/{use-native-gesture.md => use-native-gesture.mdx} (97%) rename packages/docs-gesture-handler/docs/hooks/{use-pan-gesture.md => use-pan-gesture.mdx} (99%) rename packages/docs-gesture-handler/docs/hooks/{use-pinch-gesture.md => use-pinch-gesture.mdx} (97%) rename packages/docs-gesture-handler/docs/hooks/{use-rotation-gesture.md => use-rotation-gesture.mdx} (96%) rename packages/docs-gesture-handler/docs/hooks/{use-tap-gesture.md => use-tap-gesture.mdx} (99%) diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-callbacks.md b/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-callbacks.mdx similarity index 50% rename from packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-callbacks.md rename to packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-callbacks.mdx index 446234e8ff..3ccef9036b 100644 --- a/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-callbacks.md +++ b/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-callbacks.mdx @@ -1,9 +1,13 @@ +import CodeBlock from '@theme/CodeBlock'; + ### Callbacks common to all continuous gestures: ### onUpdate -```ts -onUpdate: (event: HandlerData) => void -``` +{ + + {`onUpdate: (event: ${props.gesture}HandlerData) => void`} + +} Set the callback that is being called every time the gesture receives an update while it's active. diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.md b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.mdx similarity index 73% rename from packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.md rename to packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.mdx index e23a88715a..8872630dfc 100644 --- a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.md +++ b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.mdx @@ -1,34 +1,44 @@ +import CodeBlock from '@theme/CodeBlock'; + ### Callbacks common to all gestures: ### onBegin -```ts -onBegin: (event: HandlerData) => void -``` +{ + + {`onBegin: (event: ${props.gesture}HandlerData) => void`} + +} Set the callback that is being called when given gesture handler starts receiving touches. At the moment of this callback the handler is not yet in an active state and we don't know yet if it will recognize the gesture at all. ### onActivate -```ts -onActivate: (event: HandlerData) => void -``` +{ + + {`onActivate: (event: ${props.gesture}HandlerData) => void`} + +} Set the callback that is being called when the gesture is recognized by the handler and it transitions to the active state. ### onDeactivate -```ts -onDeactivate: (event: HandlerData) => void -``` +{ + + {`onDeactivate: (event: ${props.gesture}HandlerData, didSucceed: boolean) => void`} + +} Set the callback that is being called when the gesture that was recognized by the handler finishes. It will be called only if the handler was previously in the active state. ### onFinalize -```ts -onFinalize: (event: HandlerData) => void -``` +{ + + {`onFinalize: (event: ${props.gesture}HandlerData, didSucceed: boolean) => void`} + +} Set the callback that is being called when the handler finalizes handling gesture - the gesture was recognized and has finished or it failed to recognize. diff --git a/packages/docs-gesture-handler/docs/hooks/use-fling-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-fling-gesture.mdx similarity index 99% rename from packages/docs-gesture-handler/docs/hooks/use-fling-gesture.md rename to packages/docs-gesture-handler/docs/hooks/use-fling-gesture.mdx index 9a38c32113..8354dce3d6 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-fling-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-fling-gesture.mdx @@ -27,7 +27,7 @@ import FlingGestureBasicSrc from '!!raw-loader!@site/static/examples/FlingGestur import BaseEventData from './\_shared/base-gesture-event-data.md'; import BaseGestureConfig from './\_shared/base-gesture-config.md'; -import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; A discrete gesture that activates when the movement is sufficiently long and fast. Gesture gets [ACTIVE](/docs/fundamentals/states-events#active) when movement is sufficiently long and it does not take too much time. @@ -148,7 +148,7 @@ Allows users to choose which mouse button should handler respond to. Arguments c ## Callbacks - + ## Event data diff --git a/packages/docs-gesture-handler/docs/hooks/use-hover-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-hover-gesture.mdx similarity index 97% rename from packages/docs-gesture-handler/docs/hooks/use-hover-gesture.md rename to packages/docs-gesture-handler/docs/hooks/use-hover-gesture.mdx index 09a4683514..664c92a78f 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-hover-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-hover-gesture.mdx @@ -27,8 +27,8 @@ import HoverGestureBasicSrc from '!!raw-loader!@site/static/examples/HoverGestur import BaseEventData from './\_shared/base-gesture-event-data.md'; import BaseGestureConfig from './\_shared/base-gesture-config.md'; -import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; -import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.mdx'; A continuous gesture that can recognize hovering above the view it's attached to. The hover effect may be activated by moving a mouse or a stylus over the view. @@ -106,8 +106,8 @@ Visual effect applied to the view while the view is hovered. Defaults to `HoverE ## Callbacks - - + + ## Event data diff --git a/packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.mdx similarity index 98% rename from packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.md rename to packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.mdx index f61e8d6c5e..c313d11f30 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.mdx @@ -27,7 +27,7 @@ import LongPressGestureBasicSrc from '!!raw-loader!@site/static/examples/LongPre import BaseEventData from './\_shared/base-gesture-event-data.md'; import BaseGestureConfig from './\_shared/base-gesture-config.md'; -import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; A discrete gesture that activates when the corresponding view is pressed for a sufficiently long time. This gesture's state will turn into [END](/docs/fundamentals/states-events#end) immediately after the finger is released. @@ -126,7 +126,7 @@ Allows users to choose which mouse button should handler respond to. Arguments c ## Callbacks - + ## Event data diff --git a/packages/docs-gesture-handler/docs/hooks/use-manual-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-manual-gesture.mdx similarity index 89% rename from packages/docs-gesture-handler/docs/hooks/use-manual-gesture.md rename to packages/docs-gesture-handler/docs/hooks/use-manual-gesture.mdx index 6729e79bca..31eda7ca3c 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-manual-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-manual-gesture.mdx @@ -7,8 +7,8 @@ sidebar_position: 9 import BaseEventData from './\_shared/base-gesture-event-data.md'; import BaseGestureConfig from './\_shared/base-gesture-config.md'; -import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; -import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.mdx'; A plain gesture that has no specific activation criteria nor event data set. Its state has to be controlled manually using a [state manager](/docs/gestures/state-manager). It will not fail when all the pointers are lifted from the screen. @@ -41,8 +41,8 @@ export default function App() { ## Callbacks - - + + ## Event data diff --git a/packages/docs-gesture-handler/docs/hooks/use-native-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-native-gesture.mdx similarity index 97% rename from packages/docs-gesture-handler/docs/hooks/use-native-gesture.md rename to packages/docs-gesture-handler/docs/hooks/use-native-gesture.mdx index b62abd37f1..500e548629 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-native-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-native-gesture.mdx @@ -7,8 +7,8 @@ sidebar_position: 8 import BaseEventData from './\_shared/base-gesture-event-data.md'; import BaseGestureConfig from './\_shared/base-gesture-config.md'; -import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; -import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.mdx'; 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. @@ -108,7 +108,7 @@ When `true`, cancels all other gesture handlers when changes its state to [`ACTI ## Callbacks - + ## Event data diff --git a/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.mdx similarity index 99% rename from packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md rename to packages/docs-gesture-handler/docs/hooks/use-pan-gesture.mdx index c6b21e5305..b46c40ac55 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.mdx @@ -15,8 +15,8 @@ import PanGestureBasicSrc from '!!raw-loader!@site/static/examples/PanGestureBas import BaseEventData from './\_shared/base-gesture-event-data.md'; import BaseGestureConfig from './\_shared/base-gesture-config.md'; import BaseContinuousGestureConfig from './\_shared/base-continuous-gesture-config.md'; -import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; -import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.mdx';
@@ -241,8 +241,8 @@ Allows users to choose which mouse button should handler respond to. Arguments c ## Callbacks - - + + ## Event data diff --git a/packages/docs-gesture-handler/docs/hooks/use-pinch-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-pinch-gesture.mdx similarity index 97% rename from packages/docs-gesture-handler/docs/hooks/use-pinch-gesture.md rename to packages/docs-gesture-handler/docs/hooks/use-pinch-gesture.mdx index 3e88a006e9..f6b2e88aa1 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-pinch-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-pinch-gesture.mdx @@ -28,8 +28,8 @@ import PinchGestureBasicSrc from '!!raw-loader!@site/static/examples/PinchGestur import BaseEventData from './\_shared/base-gesture-event-data.md'; import BaseGestureConfig from './\_shared/base-gesture-config.md'; import BaseContinuousGestureConfig from './\_shared/base-continuous-gesture-config.md'; -import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; -import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.mdx'; A continuous gesture that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. The gesture [activates](/docs/fundamentals/states-events#active) when fingers are placed on the screen and change their position. @@ -113,8 +113,8 @@ const styles = StyleSheet.create({ ## Callbacks - - + + ## Event data diff --git a/packages/docs-gesture-handler/docs/hooks/use-rotation-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-rotation-gesture.mdx similarity index 96% rename from packages/docs-gesture-handler/docs/hooks/use-rotation-gesture.md rename to packages/docs-gesture-handler/docs/hooks/use-rotation-gesture.mdx index dc7b338d8c..ee3ebfce8b 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-rotation-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-rotation-gesture.mdx @@ -28,8 +28,8 @@ import RotationGestureBasicSrc from '!!raw-loader!@site/static/examples/Rotation import BaseEventData from './\_shared/base-gesture-event-data.md'; import BaseGestureConfig from './\_shared/base-gesture-config.md'; import BaseContinuousGestureConfig from './\_shared/base-continuous-gesture-config.md'; -import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; -import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.mdx'; A continuous gesture that can recognize a rotation gesture and track its movement. @@ -110,8 +110,8 @@ const styles = StyleSheet.create({ ## Callbacks - - + + ## Event data diff --git a/packages/docs-gesture-handler/docs/hooks/use-tap-gesture.md b/packages/docs-gesture-handler/docs/hooks/use-tap-gesture.mdx similarity index 99% rename from packages/docs-gesture-handler/docs/hooks/use-tap-gesture.md rename to packages/docs-gesture-handler/docs/hooks/use-tap-gesture.mdx index 3d845de681..b13bcb9f36 100644 --- a/packages/docs-gesture-handler/docs/hooks/use-tap-gesture.md +++ b/packages/docs-gesture-handler/docs/hooks/use-tap-gesture.mdx @@ -27,7 +27,7 @@ import TapGestureBasicSrc from '!!raw-loader!@site/static/examples/TapGestureBas import BaseEventData from './\_shared/base-gesture-event-data.md'; import BaseGestureConfig from './\_shared/base-gesture-config.md'; -import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; A discrete gesture that recognizes one or many taps. @@ -170,7 +170,7 @@ Allows users to choose which mouse button should handler respond to. Arguments c ## Callbacks - + ## Event data From b96d788d37bc850deac209fdd2c7a1f792bb2f1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Tue, 16 Dec 2025 15:32:25 +0100 Subject: [PATCH 16/45] Bye bye API 2 --- .../base-continuous-gesture-callbacks.mdx | 0 .../_shared/base-continuous-gesture-config.md | 6 +- .../_shared/base-gesture-callbacks.mdx | 0 .../gestures/_shared/base-gesture-config.md | 86 +++- .../_shared/base-gesture-event-data.md | 30 +- .../gesture-composition.md | 0 .../{hooks => gestures}/use-fling-gesture.mdx | 0 .../{hooks => gestures}/use-hover-gesture.mdx | 0 .../use-long-press-gesture.mdx | 0 .../use-manual-gesture.mdx | 0 .../use-native-gesture.mdx | 0 .../{hooks => gestures}/use-pan-gesture.mdx | 0 .../{hooks => gestures}/use-pinch-gesture.mdx | 0 .../use-rotation-gesture.mdx | 0 .../{hooks => gestures}/use-tap-gesture.mdx | 0 .../hooks/_shared/base-gesture-event-data.md | 27 -- .../docs-gesture-handler/docusaurus.config.js | 2 +- .../version-2.x/components/_category_.json | 7 + .../version-2.x/components/buttons.mdx | 178 ++++++++ .../version-2.x/components/pressable.mdx | 162 +++++++ .../components/reanimated-drawer-layout.mdx | 201 +++++++++ .../components/reanimated_swipeable.md | 251 +++++++++++ .../version-2.x/components/touchables.md | 56 +++ .../version-2.x/fundamentals/_category_.json | 7 + .../fundamentals/gesture-composition.md | 408 ++++++++++++++++++ .../version-2.x/fundamentals/installation.md | 177 ++++++++ .../version-2.x/fundamentals/introduction.md | 122 ++++++ .../fundamentals/states-events.mdx | 89 ++++ .../gesture-handlers/_category_.json | 0 .../gesture-handlers/about-handlers.md | 0 .../gesture-handlers/common-gh.md | 0 .../gesture-handlers/create-native-wrapper.md | 0 .../version-2.x}/gesture-handlers/fling-gh.md | 0 .../version-2.x}/gesture-handlers/force-gh.md | 0 .../gesture-handlers/interactions.md | 0 .../gesture-handlers/longpress-gh.md | 0 .../gesture-handlers/nativeview-gh.md | 0 .../version-2.x}/gesture-handlers/pan-gh.md | 0 .../version-2.x}/gesture-handlers/pinch-gh.md | 0 .../gesture-handlers/rotation-gh.md | 0 .../version-2.x}/gesture-handlers/tap-gh.md | 0 .../version-2.x/gestures/_category_.json | 7 + .../base-continuous-gesture-callbacks.md | 0 .../_shared/base-continuous-gesture-config.md | 6 +- .../_shared/base-gesture-callbacks.md | 0 .../gestures}/_shared/base-gesture-config.md | 86 +--- .../_shared/base-gesture-event-data.md | 19 + .../_shared/gesture-detector-functional1.md | 0 .../gestures/composed-gestures.md | 0 .../version-2.x}/gestures/fling-gesture.md | 0 .../gestures/force-touch-gesture.md | 0 .../version-2.x}/gestures/gesture-detector.md | 0 .../version-2.x}/gestures/gesture.md | 0 .../version-2.x}/gestures/hover-gesture.md | 0 .../gestures/long-press-gesture.md | 0 .../version-2.x}/gestures/manual-gesture.md | 0 .../version-2.x}/gestures/native-gesture.md | 0 .../version-2.x}/gestures/pan-gesture.md | 0 .../version-2.x}/gestures/pinch-gesture.md | 0 .../version-2.x}/gestures/rotation-gesture.md | 0 .../version-2.x}/gestures/state-manager.md | 0 .../version-2.x}/gestures/tap-gesture.md | 0 .../version-2.x}/gestures/touch-events.md | 0 .../version-2.x/guides/_category_.json | 7 + .../guides/manual-gestures/_steps/step1.md | 7 + .../guides/manual-gestures/_steps/step2.md | 41 ++ .../guides/manual-gestures/_steps/step3.md | 31 ++ .../guides/manual-gestures/_steps/step4.md | 15 + .../guides/manual-gestures/_steps/step5.md | 13 + .../guides/manual-gestures/_steps/step6.md | 17 + .../guides/manual-gestures/_steps/step7.md | 10 + .../guides/manual-gestures/index.md | 62 +++ .../guides/migrating-off-rnghenabledroot.md | 49 +++ .../guides/quickstart/_steps/step1.md | 13 + .../guides/quickstart/_steps/step2.md | 12 + .../guides/quickstart/_steps/step3.md | 25 ++ .../guides/quickstart/_steps/step4.md | 9 + .../guides/quickstart/_steps/step5.md | 38 ++ .../version-2.x/guides/quickstart/index.md | 56 +++ .../version-2.x/guides/swipe-and-scroll.md | 13 + .../version-2.x/guides/testing.md | 129 ++++++ .../version-2.x/guides/troubleshooting.md | 130 ++++++ .../version-2.x/guides/upgrading-to-2.md | 117 +++++ .../under-the-hood/_category_.json | 7 + .../under-the-hood/how-does-it-work.md | 22 + .../version-2.x/under-the-hood/state.md | 91 ++++ .../version-2.x-sidebars.json | 8 + packages/docs-gesture-handler/versions.json | 5 +- 88 files changed, 2722 insertions(+), 132 deletions(-) rename packages/docs-gesture-handler/docs/{hooks => gestures}/_shared/base-continuous-gesture-callbacks.mdx (100%) rename packages/docs-gesture-handler/docs/{hooks => gestures}/_shared/base-gesture-callbacks.mdx (100%) rename packages/docs-gesture-handler/docs/{hooks => gestures}/gesture-composition.md (100%) rename packages/docs-gesture-handler/docs/{hooks => gestures}/use-fling-gesture.mdx (100%) rename packages/docs-gesture-handler/docs/{hooks => gestures}/use-hover-gesture.mdx (100%) rename packages/docs-gesture-handler/docs/{hooks => gestures}/use-long-press-gesture.mdx (100%) rename packages/docs-gesture-handler/docs/{hooks => gestures}/use-manual-gesture.mdx (100%) rename packages/docs-gesture-handler/docs/{hooks => gestures}/use-native-gesture.mdx (100%) rename packages/docs-gesture-handler/docs/{hooks => gestures}/use-pan-gesture.mdx (100%) rename packages/docs-gesture-handler/docs/{hooks => gestures}/use-pinch-gesture.mdx (100%) rename packages/docs-gesture-handler/docs/{hooks => gestures}/use-rotation-gesture.mdx (100%) rename packages/docs-gesture-handler/docs/{hooks => gestures}/use-tap-gesture.mdx (100%) delete mode 100644 packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-event-data.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/components/_category_.json create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/components/buttons.mdx create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/components/pressable.mdx create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated-drawer-layout.mdx create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated_swipeable.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/components/touchables.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/_category_.json create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/gesture-composition.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/installation.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/introduction.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/states-events.mdx rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/_category_.json (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/about-handlers.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/common-gh.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/create-native-wrapper.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/fling-gh.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/force-gh.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/interactions.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/longpress-gh.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/nativeview-gh.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/pan-gh.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/pinch-gh.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/rotation-gh.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gesture-handlers/tap-gh.md (100%) create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_category_.json rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/_shared/base-continuous-gesture-callbacks.md (100%) rename packages/docs-gesture-handler/{docs/hooks => versioned_docs/version-2.x/gestures}/_shared/base-continuous-gesture-config.md (74%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/_shared/base-gesture-callbacks.md (100%) rename packages/docs-gesture-handler/{docs/hooks => versioned_docs/version-2.x/gestures}/_shared/base-gesture-config.md (75%) create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-event-data.md rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/_shared/gesture-detector-functional1.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/composed-gestures.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/fling-gesture.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/force-touch-gesture.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/gesture-detector.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/gesture.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/hover-gesture.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/long-press-gesture.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/manual-gesture.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/native-gesture.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/pan-gesture.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/pinch-gesture.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/rotation-gesture.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/state-manager.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/tap-gesture.md (100%) rename packages/docs-gesture-handler/{docs => versioned_docs/version-2.x}/gestures/touch-events.md (100%) create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/_category_.json create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step1.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step2.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step3.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step4.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step5.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step6.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step7.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/index.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/migrating-off-rnghenabledroot.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step1.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step2.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step3.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step4.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step5.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/index.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/swipe-and-scroll.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/testing.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/troubleshooting.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/guides/upgrading-to-2.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/under-the-hood/_category_.json create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/under-the-hood/how-does-it-work.md create mode 100644 packages/docs-gesture-handler/versioned_docs/version-2.x/under-the-hood/state.md create mode 100644 packages/docs-gesture-handler/versioned_sidebars/version-2.x-sidebars.json diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-callbacks.mdx b/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-callbacks.mdx similarity index 100% rename from packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-callbacks.mdx rename to packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-callbacks.mdx diff --git a/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-config.md b/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-config.md index 71ca8db252..af148874b5 100644 --- a/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-config.md +++ b/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-config.md @@ -1,5 +1,9 @@ ### Properties common to all continuous gestures: -### `manualActivation(value: boolean)` +### manualActivation + +```ts +manualActivation: boolean | SharedValue; +``` When `true` the handler will not activate by itself even if its activation criteria are met. Instead you can manipulate its state using [state manager](/docs/gestures/state-manager/). diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.mdx b/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-callbacks.mdx similarity index 100% rename from packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-callbacks.mdx rename to packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-callbacks.mdx diff --git a/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-config.md b/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-config.md index 2e2fb6d425..9484d5194d 100644 --- a/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-config.md +++ b/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-config.md @@ -1,19 +1,48 @@ ### Properties common to all gestures: -### `enabled(value: boolean)` +### enabled + +```ts +enabled: boolean | SharedValue; +``` Indicates whether the given handler should be analyzing stream of touch events or not. When set to `false` we can be sure that the handler's state will **never** become [`ACTIVE`](/docs/fundamentals/states-events#active). If the value gets updated while the handler already started recognizing a gesture, then the handler's state it will immediately change to [`FAILED`](/docs/fundamentals/states-events#failed) or [`CANCELLED`](/docs/fundamentals/states-events#cancelled) (depending on its current state). Default value is `true`. -### `shouldCancelWhenOutside(value: boolean)` +### shouldCancelWhenOutside + +```ts +shouldCancelWhenOutside: boolean | SharedValue; +``` When `true` the handler will [cancel](/docs/fundamentals/states-events#cancelled) or [fail](/docs/fundamentals/states-events#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. Default value of this property is different depending on the handler type. -Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGesture`](/docs/gestures/long-press-gesture) and [`TapGesture`](/docs/gestures/tap-gesture) which default to `true`. - -### `hitSlop(settings)` +Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGesture`](/docs/hooks/use-long-press-gesture) and [`TapGesture`](/docs/hooks/use-tap-gesture) which default to `true`. + +### hitSlop + +```ts +hitSlop: HitSlop | SharedValue; +``` + +```ts +type HitSlop = + | number + | null + | undefined + | Partial< + Record< + 'left' | 'right' | 'top' | 'bottom' | 'vertical' | 'horizontal', + number + > + > + | Record<'width' | 'left', number> + | Record<'width' | 'right', number> + | Record<'height' | 'top', number> + | Record<'height' | 'bottom', number>; +``` This parameter enables control over what part of the connected view area can be used to [begin](/docs/fundamentals/states-events#began) recognizing the gesture. When a negative number is provided the bounds of the view will reduce the area by the given number of points in each of the sides evenly. @@ -27,42 +56,65 @@ Specifying `width` or `height` is useful if we only want the gesture to activate **IMPORTANT:** Note that this parameter is primarily designed to reduce the area where gesture can activate. Hence it is only supported for all the values (except `width` and `height`) to be non positive (0 or lower). Although on Android it is supported for the values to also be positive and therefore allow to expand beyond view bounds but not further than the parent view bounds. To achieve this effect on both platforms you can use React Native's View [hitSlop](https://reactnative.dev/docs/view.html#hitslop) property. -### `withRef(ref)` +### testID -Sets a ref to the gesture object, allowing for interoperability with the old -API. - -### `withTestId(testID)` +```ts +testID: string; +``` Sets a `testID` property for gesture object, allowing for querying for it in tests. -### `cancelsTouchesInView(value)` (**iOS only**) +### cancelsTouchesInView (**iOS only**) + +```ts +cancelsTouchesInView: boolean | SharedValue; +``` Accepts a boolean value. When `true`, the gesture will cancel touches for native UI components (`UIButton`, `UISwitch`, etc) it's attached to when it becomes [`ACTIVE`](/docs/fundamentals/states-events#active). Default value is `true`. -### `runOnJS(value: boolean)` +### runOnJS + +```ts +runOnJS: boolean | SharedValue; +``` When `react-native-reanimated` is installed, the callbacks passed to the gestures are automatically workletized and run on the UI thread when called. This option allows for changing this behavior: when `true`, all the callbacks will be run on the JS thread instead of the UI thread, regardless of whether they are worklets or not. Defaults to `false`. -### `simultaneousWithExternalGesture(otherGesture1, otherGesture2, ...)` +### simultaneousWith + +```ts +simultaneousWith: Gesture | Gesture[] +``` Adds a gesture that should be recognized simultaneously with this one. **IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](/docs/fundamentals/gesture-composition). [`GestureDetector`](/docs/gestures/gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. -### `requireExternalGestureToFail(otherGesture1, otherGesture2, ...)` +### requireToFail + +```ts +requireToFail: Gesture | Gesture[] +``` Adds a relation requiring another gesture to fail, before this one can activate. -### `blocksExternalGesture(otherGesture1, otherGesture2, ...)` +### block + +```ts +block: Gesture | Gesture[] +``` Adds a relation that makes other gestures wait with activation until this gesture fails (or doesn't start at all). **IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](/docs/fundamentals/gesture-composition).[`GestureDetector`](/docs/gestures/gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. -### `activeCursor(value)` (Web only) +### activeCursor + +```ts +activeCursor: ActiveCursor | SharedValue; +``` -This parameter allows to specify which cursor should be used when gesture activates. Supports all CSS cursor values (e.g. `"grab"`, `"zoom-in"`). Default value is set to `"auto"`. +This parameter allows to specify which cursor should be used when gesture activates. Supports all [CSS cursor values](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/cursor#keyword) (e.g. `"grab"`, `"zoom-in"`). Default value is set to `"auto"`. diff --git a/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-event-data.md b/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-event-data.md index 6d6767d639..86fb0115ff 100644 --- a/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-event-data.md +++ b/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-event-data.md @@ -1,19 +1,27 @@ ### Event attributes common to all gestures: -### `state` +### numberOfPointers -Current [state](/docs/fundamentals/states-events) of the handler. Expressed as one of the constants exported under `State` object by the library. - -### `numberOfPointers` +```ts +numberOfPointers: number; +``` Represents the number of pointers (fingers) currently placed on the screen. -### `pointerType` +### pointerType + +```ts +pointerType: PointerType; +``` -Indicates the type of pointer device in use. This value is represented by the `PointerType` enum, which includes the following fields: +```ts +enum PointerType { + TOUCH, + STYLUS, + MOUSE, + KEY, + OTHER, +} +``` -- `TOUCH` - represents finger -- `STYLUS` - represents stylus or digital pen -- `MOUSE` - represents computer mouse -- `KEY` - represents keyboard -- `OTHER` - represents unknown device type that is not relevant +Indicates the type of pointer device in use. diff --git a/packages/docs-gesture-handler/docs/hooks/gesture-composition.md b/packages/docs-gesture-handler/docs/gestures/gesture-composition.md similarity index 100% rename from packages/docs-gesture-handler/docs/hooks/gesture-composition.md rename to packages/docs-gesture-handler/docs/gestures/gesture-composition.md diff --git a/packages/docs-gesture-handler/docs/hooks/use-fling-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-fling-gesture.mdx similarity index 100% rename from packages/docs-gesture-handler/docs/hooks/use-fling-gesture.mdx rename to packages/docs-gesture-handler/docs/gestures/use-fling-gesture.mdx diff --git a/packages/docs-gesture-handler/docs/hooks/use-hover-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-hover-gesture.mdx similarity index 100% rename from packages/docs-gesture-handler/docs/hooks/use-hover-gesture.mdx rename to packages/docs-gesture-handler/docs/gestures/use-hover-gesture.mdx diff --git a/packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-long-press-gesture.mdx similarity index 100% rename from packages/docs-gesture-handler/docs/hooks/use-long-press-gesture.mdx rename to packages/docs-gesture-handler/docs/gestures/use-long-press-gesture.mdx diff --git a/packages/docs-gesture-handler/docs/hooks/use-manual-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-manual-gesture.mdx similarity index 100% rename from packages/docs-gesture-handler/docs/hooks/use-manual-gesture.mdx rename to packages/docs-gesture-handler/docs/gestures/use-manual-gesture.mdx diff --git a/packages/docs-gesture-handler/docs/hooks/use-native-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-native-gesture.mdx similarity index 100% rename from packages/docs-gesture-handler/docs/hooks/use-native-gesture.mdx rename to packages/docs-gesture-handler/docs/gestures/use-native-gesture.mdx diff --git a/packages/docs-gesture-handler/docs/hooks/use-pan-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-pan-gesture.mdx similarity index 100% rename from packages/docs-gesture-handler/docs/hooks/use-pan-gesture.mdx rename to packages/docs-gesture-handler/docs/gestures/use-pan-gesture.mdx diff --git a/packages/docs-gesture-handler/docs/hooks/use-pinch-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-pinch-gesture.mdx similarity index 100% rename from packages/docs-gesture-handler/docs/hooks/use-pinch-gesture.mdx rename to packages/docs-gesture-handler/docs/gestures/use-pinch-gesture.mdx diff --git a/packages/docs-gesture-handler/docs/hooks/use-rotation-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-rotation-gesture.mdx similarity index 100% rename from packages/docs-gesture-handler/docs/hooks/use-rotation-gesture.mdx rename to packages/docs-gesture-handler/docs/gestures/use-rotation-gesture.mdx diff --git a/packages/docs-gesture-handler/docs/hooks/use-tap-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-tap-gesture.mdx similarity index 100% rename from packages/docs-gesture-handler/docs/hooks/use-tap-gesture.mdx rename to packages/docs-gesture-handler/docs/gestures/use-tap-gesture.mdx diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-event-data.md b/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-event-data.md deleted file mode 100644 index 86fb0115ff..0000000000 --- a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-event-data.md +++ /dev/null @@ -1,27 +0,0 @@ -### Event attributes common to all gestures: - -### numberOfPointers - -```ts -numberOfPointers: number; -``` - -Represents the number of pointers (fingers) currently placed on the screen. - -### pointerType - -```ts -pointerType: PointerType; -``` - -```ts -enum PointerType { - TOUCH, - STYLUS, - MOUSE, - KEY, - OTHER, -} -``` - -Indicates the type of pointer device in use. diff --git a/packages/docs-gesture-handler/docusaurus.config.js b/packages/docs-gesture-handler/docusaurus.config.js index 42974be4b2..9521346f34 100644 --- a/packages/docs-gesture-handler/docusaurus.config.js +++ b/packages/docs-gesture-handler/docusaurus.config.js @@ -46,7 +46,7 @@ const config = { lastVersion: 'current', // <- this makes 2.x docs as default versions: { current: { - label: '2.x', + label: '3.x', }, }, }, diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/_category_.json b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/_category_.json new file mode 100644 index 0000000000..b209621c3f --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Components", + "position": 4, + "link": { + "type": "generated-index" + } +} diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/buttons.mdx b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/buttons.mdx new file mode 100644 index 0000000000..e20bff3256 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/buttons.mdx @@ -0,0 +1,178 @@ +--- +id: buttons +title: Buttons +sidebar_label: Buttons +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import GifGallery from '@site/components/GifGallery'; + + + + + +Gesture handler library provides native components that can act as buttons. These can be treated as a replacement to `TouchableHighlight` or `TouchableOpacity` from RN core. Gesture handler's buttons recognize touches in native which makes the recognition process deterministic, allows for rendering ripples on Android in highly performant way (`TouchableNativeFeedback` requires that touch event does a roundtrip to JS before we can update ripple effect, which makes ripples lag a bit on older phones), and provides native and platform default interaction for buttons that are placed in a scrollable container (in which case the interaction is slightly delayed to prevent button from highlighting when you fling). + +Currently Gesture handler library exposes three components that render native touchable elements under the hood: + +- [`BaseButton`](/docs/components/buttons/#basebutton) +- [`RectButton`](/docs/components/buttons/#rectbutton) +- [`BorderlessButton`](/docs/components/buttons/#borderlessbutton) + +On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](/docs/gesture-handlers/common-gh/) and `NativeViewGestureHandler`'s [extra properties](/docs/gesture-handlers/nativeview-gh#properties) to be applied to them. + +**IMPORTANT**: In order to make buttons accessible, you have to wrap your children in a `View` with `accessible` and `accessibilityRole="button"` props. +Example: + +```javascript +// Not accessible: +const NotAccessibleButton = () => ( + + Foo + +); +// Accessible: +const AccessibleButton = () => ( + + + Bar + + +); +``` + +It is applicable for both iOS and Android platform. On iOS, you won't be able to even select the button, on Android you won't be able to click it in accessibility mode. + +## `BaseButton` + +Can be used as a base class if you'd like to implement some custom interaction for when the button is pressed. + +Below is a list of properties specific to `BaseButton` component: + +### `onActiveStateChange` + +function that gets triggered when button changes from inactive to active and vice versa. It passes active state as a boolean variable as a first parameter for that method. + +### `onPress` + +function that gets triggered when the button gets pressed (analogous to `onPress` in `TouchableHighlight` from RN core). + +### `onLongPress` + +function that gets triggered when the button gets pressed for at least `delayLongPress` milliseconds. + +### `rippleColor` (**Android only**) + +defines color of native [ripple](https://developer.android.com/reference/android/graphics/drawable/RippleDrawable) animation used since API level 21. + +### `exclusive` + +defines if more than one button could be pressed simultaneously. By default set `true`. + +### `delayLongPress` + +defines the delay, in milliseconds, after which the `onLongPress` callback gets called. By default set to 600. + +## `RectButton` + +This type of button component should be used when you deal with rectangular elements or blocks of content that can be pressed, for example table rows or buttons with text and icons. This component provides a platform specific interaction, rendering a rectangular ripple on Android or highlighting the background on iOS and on older versions of Android. In addition to the props of [`BaseButton`](/docs/components/buttons#basebutton), it accepts the following: + +Below is a list of properties specific to `RectButton` component: + +### `underlayColor` + +this is the background color that will be dimmed when button is in active state. + +### `activeOpacity` (**iOS only**) + +opacity applied to the underlay when button is in active state. + +## `BorderlessButton` + +This type of button component should be used with simple icon-only or text-only buttons. The interaction will be different depending on platform: on Android a borderless ripple will be rendered (it means that the ripple will animate into a circle that can span outside of the view bounds), whereas on iOS the button will be dimmed (similar to how `TouchableOpacity` works). In addition to the props of [`BaseButton`](/docs/components/buttons#basebutton), it accepts the following: + +Below is a list of properties specific to `BorderlessButton` component: + +### `borderless` (**Android only**) + +set this to `false` if you want the ripple animation to render only within view bounds. + +### `activeOpacity` (**iOS only**) + +opacity applied to the button when it is in an active state. + +## Design patterns + +Components listed here were not designed to behave and look in the same way on both platforms but rather to be used for handling similar behaviour on iOS and Android taking into consideration their's design concepts. + +If you wish to get specific information about platforms design patterns, visit [official Apple docs](https://developer.apple.com/design/human-interface-guidelines/components/menus-and-actions/buttons) and [Material.io guideline](https://material.io/components/buttons#text-button), which widely describe how to implement coherent design. + +This library allows to use native components with native feedback in adequate situations. + +If you do not wish to implement custom design approach, `RectButton` and `BorderlessButton` seem to be absolutely enough and there's no need to use anything else. In all the remaining cases you can always rely on `BaseButton` which is a superclass for the other button classes and can be used as a generic `Touchable` replacement that can be customized to your needs. + +Below we list some of the common usecases for button components to be used along with the type of button that should be used according to the platform specific design guidelines. + +### Lists and action buttons + +If you have a list with clickable items or have an action button that need to display as a separate UI block (vs being inlined in a text) you should use `RectButton`. It changes opacity on click and additionally supports a ripple effect on Android. + + + + + + +To determine emphasis of button it's vital to use fill color or leave it transparent especially on Android. +For medium emphasis you may consider outlined buttons which are used for lower impact than fill buttons. + + + + + +### Icon or text only buttons + +Use `BorderlessButton` for simple icon-only or text-only buttons. The interaction will be different depending on platform: on Android a borderless ripple will be rendered, whereas on iOS the button will be dimmed. +It should be used if you wish to handle non-crucial actions and supportive behaviour. + + + + + + +### `PureNativeButton` + +Use a `PureNativeButton` for accessing the native Component used for build more complex buttons listed above. +It's normally is not recommended to use, but it might be useful if we want to wrap it using Animated or Reanimated. + +```javascript +import { + createNativeWrapper, + PureNativeButton, +} from 'react-native-gesture-handler'; +import Animated from 'react-native-reanimated'; +const { event, Value, createAnimatedComponent } = Animated; + +const AnimatedRawButton = createNativeWrapper( + createAnimatedComponent(PureNativeButton), + { + shouldCancelWhenOutside: false, + shouldActivateOnStart: false, + } +); + +export default class App extends React.Component { + constructor(props) { + super(props); + const state = new Value(); + this._onGestureEvent = event([ + { + nativeEvent: { state }, + }, + ]); + } + + render() { + return ; + } +} +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/pressable.mdx b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/pressable.mdx new file mode 100644 index 0000000000..d7455d3973 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/pressable.mdx @@ -0,0 +1,162 @@ +--- +id: pressable +title: Pressable +sidebar_label: Pressable +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import GifGallery from '@site/components/GifGallery'; + + + + + +:::info +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. + +### Usage: + +To use `Pressable`, import it in the following way: + +```js +import { Pressable } from 'react-native-gesture-handler'; +``` + +## Properties + +### `children` + +either children or a render function that receives a boolean reflecting whether +the component is currently pressed. + +### `style` + +either view styles or a function that receives a boolean reflecting whether +the component is currently pressed and returns view styles. + +### `onPress` + +called after `onPressOut` when a single tap gesture is detected. + +### `onPressIn` + +called before `onPress` when a touch is engaged. + +### `onPressOut` + +called before `onPress` when a touch is released. + +### `onLongPress` + +called immediately after pointer has been down for at least `delayLongPress` milliseconds (`500` ms by default). + +After `onLongPress` has been called, `onPressOut` will be called as soon as the pointer is lifted and `onPress` will not be called at all. + +### `cancelable` + +whether a press gesture can be interrupted by a parent gesture such as a scroll event. Defaults to `true`. + +### `onHoverIn` (Web only) + +called when pointer is hovering over the element. + +### `onHoverOut` (Web only) + +called when pointer stops hovering over the element. + +### `delayHoverIn` (Web only) + +duration to wait after hover in before calling `onHoverIn`. + +### `delayHoverOut` (Web only) + +duration to wait after hover out before calling `onHoverOut`. + +### `delayLongPress` + +duration (in milliseconds) from `onPressIn` before `onLongPress` is called. + +### `disabled` + +whether the `Pressable` behavior is disabled. + +### `hitSlop` (Android & iOS only) + +additional distance outside of the view in which a press is detected and `onPressIn` is triggered. + +Accepts values of type `number` or [`Rect`](https://reactnative.dev/docs/rect) + +### `pressRetentionOffset` (Android & iOS only) + +additional distance outside of the view (or `hitSlop` if present) in which a touch is considered a +press before `onPressOut` is triggered. + +Accepts values of type `number` or [`Rect`](https://reactnative.dev/docs/rect) + +### `android_disableSound` (Android only) + +if `true`, doesn't play system sound on touch. + +### `android_ripple` (Android only) + +enables the Android ripple effect and configures its color, radius and other parameters. + +Accepts values of type [`RippleConfig`](https://reactnative.dev/docs/pressable#rippleconfig) + +### `testOnly_pressed` + +used only for documentation or testing (e.g. snapshot testing). + +### `unstable_pressDelay` + +duration (in milliseconds) to wait after press down before calling `onPressIn`. + +### Example: + +See the full [pressable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/apps/common-app/src/new_api/pressable/index.tsx) from `GestureHandler` example app. + +import GestureStateFlowExample from '@site/src/examples/GestureStateFlowExample'; + +```js +import { View, Text, StyleSheet } from 'react-native'; +import { Pressable } from 'react-native-gesture-handler'; + +export default function Example() { + return ( + (pressed ? styles.highlight : styles.pressable)} + hitSlop={20} + pressRetentionOffset={20}> + + Pressable! + + + ); +} + +const styles = StyleSheet.create({ + pressable: { + width: 120, + height: 120, + backgroundColor: 'mediumpurple', + borderWidth: StyleSheet.hairlineWidth, + }, + highlight: { + width: 120, + height: 120, + backgroundColor: 'red', + borderWidth: StyleSheet.hairlineWidth, + }, + textWrapper: { + flex: 1, + justifyContent: 'center', + alignItems: 'center', + }, + text: { + color: 'black', + }, +}); +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated-drawer-layout.mdx b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated-drawer-layout.mdx new file mode 100644 index 0000000000..8a5e2e6584 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated-drawer-layout.mdx @@ -0,0 +1,201 @@ +--- +id: reanimated-drawer-layout +title: Reanimated Drawer Layout +sidebar_label: Reanimated Drawer Layout +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +Cross-platform replacement for the React Native's [DrawerLayoutAndroid](http://reactnative.dev/docs/drawerlayoutandroid.html) component. +For detailed usage of standard parameters, please refer to the [React Native docs](http://reactnative.dev/docs/drawerlayoutandroid.html). + +### Usage: + +To use it, import it in the following way: + +```js +import ReanimatedDrawerLayout from 'react-native-gesture-handler/ReanimatedDrawerLayout'; +``` + +## Properties: + +### `drawerType` + +specifies the way the drawer will be displayed. +Accepts values of the `DrawerPosition` enum. Defaults to `FRONT`. + +- `FRONT` the drawer will be displayed above the content view. +- `BACK` the drawer will be displayed below the content view, revealed by sliding away the content view. +- `SLIDE` the drawer will appear attached to the content view, opening it slides both the drawer and the content view. + +| `FRONT` | `BACK` | `SLIDE` | +| ----------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------- | +| | | | + +### `edgeWidth` + +width of the invisible, draggable area on the edge of the content view, which can be dragged to open the drawer. + +### `hideStatusBar` + +a boolean value. When set to `true`, drawer component will use [StatusBar API](http://reactnative.dev/docs/statusbar.html) to hide the OS status bar when the drawer is dragged or idle in the `open` position. + +### `statusBarAnimation` + +a string with possible values: `slide`, `none` or `fade`. Defaults to `slide`. +May be used in combination with `hideStatusBar` to select the animation used for hiding the status bar. +See [StatusBar API](http://reactnative.dev/docs/statusbar.html#statusbaranimation) docs. + +### `overlayColor` + +color of the background overlay on top of the content window when the drawer is `open`. +This color's opacity animates from 0% to 100% as the drawer transitions from closed to open. Defaults to `rgba(0, 0, 0, 0.7)`. + +### `renderNavigationView` + +a renderer function for the drawer component, provided with a `progress` parameter. + +- `progress` - `SharedValue` that indicates the progress of drawer opening/closing animation. + - equals `0` when the `drawer` is closed and `1` when the `drawer` is opened + - can be used by the `drawer` component to animated its children while the `drawer` is opening or closing + +### `onDrawerClose` + +a function which is called when the drawer has been closed. + +### `onDrawerOpen` + +a function which is called when the drawer has been opened. + +### `onDrawerSlide` + +a function which is called when drawer is moving or animating, provided with a `progress` parameter. + +- `progress` - `SharedValue` that indicates the progress of drawer opening/closing animation. + - equals `0` when the `drawer` is closed and `1` when the `drawer` is opened + - can be used by the `drawer` component to animated its children while the `drawer` is opening or closing + +### `onDrawerStateChanged` + +a function which is called when the status of the drawer changes. It takes two arguments: + +- `newState` - interaction state of the drawer. It can be one of the following: + - `DrawerState.IDLE` + - `DrawerState.DRAGGING` + - `DrawerState.SETTLING` +- `drawerWillShow` - `true` when `drawer` started animating to `open` position, `false` otherwise. + +### `enableTrackpadTwoFingerGesture` (iOS only) + +enables two-finger gestures on supported devices, for example iPads with trackpads. +If not enabled, the gesture will require click + drag, with `enableTrackpadTwoFingerGesture` swiping with two fingers will also trigger the gesture. + +### `children` + +either a component that's rendered in the content view or a function. +If `children` is a function, it is provided with a `progress` parameter. + +- `progress` - `SharedValue` that indicates the progress of drawer opening/closing animation. + - equals `0` when the `drawer` is closed and `1` when the `drawer` is opened + - can be used by the `drawer` component to animated its children while the `drawer` is opening or closing + +### `mouseButton(value: MouseButton)` (Web & Android only) + +allows users to choose which mouse button should handler respond to. +The enum `MouseButton` consists of the following predefined fields: + +- `LEFT` +- `RIGHT` +- `MIDDLE` +- `BUTTON_4` +- `BUTTON_5` +- `ALL` + +Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Defaults to `MouseButton.LEFT`. + +### `enableContextMenu(value: boolean)` (Web only) + +specifies whether context menu should be enabled after clicking on underlying view with right mouse button. Defaults to `false`. + +## Methods + +### `openDrawer(options)` + +`openDrawer` accepts an optional `options` parameter, which is an object with the following optional properties: + +- `initialVelocity` - the initial velocity of the object attached to the spring. Defaults to `0`. +- `animationSpeed` - controls speed of the animation. Defaults to `1`. + +### `closeDrawer(options)` + +`closeDrawer` accepts an optional `options` parameter, which is an object with the following optional properties: + +- `initialVelocity` - initial velocity of the object attached to the spring. Defaults to `0`. +- `animationSpeed` - controls speed of the animation. Defaults to `1`. + +## Example: + +See the [reanimated drawer layout example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/apps/common-app/src/release_tests/reanimatedDrawerLayout/index.tsx) from GestureHandler example app. + +```js +import React, { useRef } from 'react'; +import { StyleSheet, Text, View } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; + +import ReanimatedDrawerLayout, { + DrawerType, + DrawerPosition, + DrawerLayoutMethods, +} from 'react-native-gesture-handler/ReanimatedDrawerLayout'; + +const DrawerPage = () => { + return ( + + Lorem ipsum + + ); +}; + +export default function ReanimatedDrawerExample() { + const drawerRef = useRef < DrawerLayoutMethods > null; + const tapGesture = Gesture.Tap() + .runOnJS(true) + .onStart(() => drawerRef.current?.openDrawer()); + + return ( + } + drawerPosition={DrawerPosition.LEFT} + drawerType={DrawerType.FRONT}> + + + + Open drawer + + + + + ); +} + +const styles = StyleSheet.create({ + drawerContainer: { + flex: 1, + justifyContent: 'center', + alignItems: 'center', + backgroundColor: 'pink', + }, + innerContainer: { + flex: 1, + backgroundColor: 'white', + alignItems: 'center', + justifyContent: 'center', + gap: 20, + }, + box: { + padding: 20, + backgroundColor: 'pink', + }, +}); +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated_swipeable.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated_swipeable.md new file mode 100644 index 0000000000..bbf58d07fc --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated_swipeable.md @@ -0,0 +1,251 @@ +--- +id: reanimated_swipeable +title: Reanimated Swipeable +sidebar_label: Reanimated Swipeable +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import GifGallery from '@site/components/GifGallery' + + + + + +:::info +This component is a drop-in replacement for the `Swipeable` component, rewritten using `Reanimated`. +::: + +Reanimated `Swipeable` allows for implementing swipeable rows or similar interaction. It renders its children within a panable container allows for horizontal swiping left and right. While swiping one of two "action" containers can be shown depends on whether user swipes left or right (containers can be rendered by `renderLeftActions` or `renderRightActions` props). + +### Usage: + +To use it, import it in the following way: + +```js +import Swipeable from 'react-native-gesture-handler/ReanimatedSwipeable'; +``` + +## Properties + +### `friction` + +a number that specifies how much the visual interaction will be delayed compared to the gesture distance. +e.g. value of `1` will indicate that the swipeable panel should exactly follow the gesture, `2` means it is going to be two times "slower". + +### `leftThreshold` + +distance from the left edge at which released panel will animate to the open state (or the open panel will animate into the closed state). By default it's a half of the panel's width. + +### `rightThreshold` + +distance from the right edge at which released panel will animate to the open state (or the open panel will animate into the closed state). By default it's a half of the panel's width. + +### `dragOffsetFromLeftEdge` + +distance that the panel must be dragged from the left edge to be considered a swipe. The default value is `10`. + +### `dragOffsetFromRightEdge` + +distance that the panel must be dragged from the right edge to be considered a swipe. The default value is `10`. + +### `overshootLeft` + +a boolean value indicating if the swipeable panel can be pulled further than the left actions panel's width. It is set to `true` by default as long as the left panel render function is present. + +### `overshootRight` + +a boolean value indicating if the swipeable panel can be pulled further than the right actions panel's width. It is set to `true` by default as long as the right panel render function is present. + +### `overshootFriction` + +a number that specifies how much the visual interaction will be delayed compared to the gesture distance at overshoot. Default value is `1`, it mean no friction, for a native feel, try `8` or above. + +### `onSwipeableOpen` + +a function that is called when `swipeable` is opened (either right or left). +Receives swipe direction as an argument. + +### `onSwipeableClose` + +a function that is called when `swipeable` is closed. +Receives swipe direction as an argument. + +### `onSwipeableWillOpen` + +a function that is called when `swipeable` starts animating on open (either right or left). +Receives swipe direction as an argument. + +### `onSwipeableWillClose` + +a function that is called when `swipeable` starts animating on close. +Receives swipe direction as an argument. + +### `onSwipeableOpenStartDrag` + +a function that is called when a user starts to drag the `swipable` to open. +Receives swipe direction as an argument. + +### `onSwipeableCloseStartDrag` + +a function that is called when a user starts to drag the `swipable` to close. +Receives swipe direction as an argument. + +### `renderLeftActions` + +a function that returns a component which will be rendered under the swipeable after swiping it to the right. +The function receives the following arguments: + +- `progress` - a `SharedValue` representing swiping progress relative to the width of the returned element. + - Equals `0` when `swipeable` is closed, `1` when `swipeable` is opened. + - When the element overshoots it's opened position the value tends towards `Infinity`. +- `translation` - a horizontal offset of the `swipeable` relative to its closed position. +- `swipeableMethods` - provides an object exposing the methods listed [here](#methods). + +This function must return a `ReactNode`. + +To support `rtl` flexbox layouts use `flexDirection` styling. + +### `renderRightActions` + +a function that returns a component which will be rendered under the swipeable after swiping it to the left. +The function receives the following arguments: + +- `progress` - a `SharedValue` representing swiping progress relative to the width of the returned element. + - Equals `0` when `swipeable` is closed, `1` when `swipeable` is opened. + - When the element overshoots it's opened position the value tends towards `Infinity`. +- `translation` - a horizontal offset of the `swipeable` relative to its closed position. +- `swipeableMethods` - provides an object exposing the methods listed [here](#methods). + +This function must return a `ReactNode`. + +To support `rtl` flexbox layouts use `flexDirection` styling. + +### `containerStyle` + +style object for the container (`Animated.View`), for example to override `overflow: 'hidden'`. + +### `childrenContainerStyle` + +style object for the children container (`Animated.View`), for example to apply `flex: 1`. + +### `simultaneousWithExternalGesture` + +A gesture configuration to be recognized simultaneously with the swipeable gesture. This is useful for allowing other gestures to work simultaneously with swipeable gesture handler. + +For example, to enable a pan gesture alongside the swipeable gesture: + +```jsx +const panGesture = Gesture.Pan(); + + + + +``` + +More details can be found in the [gesture composition documentation](../fundamentals/gesture-composition.md#simultaneouswithexternalgesture). + +### `enableTrackpadTwoFingerGesture` (iOS only) + +Enables two-finger gestures on supported devices, for example iPads with trackpads. +If not enabled the gesture will require click + drag, with `enableTrackpadTwoFingerGesture` swiping with two fingers will also trigger the gesture. + +### `mouseButton(value: MouseButton)` (Web & Android only) + +Allows users to choose which mouse button should handler respond to. The enum `MouseButton` consists of the following predefined fields: + +- `LEFT` +- `RIGHT` +- `MIDDLE` +- `BUTTON_4` +- `BUTTON_5` +- `ALL` + +Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`. + +### `enableContextMenu(value: boolean)` (Web only) + +Specifies whether context menu should be enabled after clicking on underlying view with right mouse button. Default value is set to `false`. + +## Methods + +Using reference to `Swipeable` it's possible to trigger some actions on it + +### `close` + +a method that closes component. + +### `openLeft` + +a method that opens component on left side. + +### `openRight` + +a method that opens component on right side. + +### `reset` + +a method that resets the swiping states of this `Swipeable` component. + +Unlike method `close`, this method does not trigger any animation. + +### Example: + +For a more in-depth presentation of differences between the new and the legacy implementations, +see [swipeable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/apps/common-app/src/release_tests/swipeableReanimation/index.tsx) from GestureHandler Example App. + +```jsx +import React from 'react'; +import { Text, StyleSheet } from 'react-native'; + +import { GestureHandlerRootView } from 'react-native-gesture-handler'; +import ReanimatedSwipeable from 'react-native-gesture-handler/ReanimatedSwipeable'; +import Reanimated, { + SharedValue, + useAnimatedStyle, +} from 'react-native-reanimated'; + +function RightAction(prog: SharedValue, drag: SharedValue) { + const styleAnimation = useAnimatedStyle(() => { + console.log('showRightProgress:', prog.value); + console.log('appliedTranslation:', drag.value); + + return { + transform: [{ translateX: drag.value + 50 }], + }; + }); + + return ( + + Text + + ); +} + +export default function Example() { + return ( + + + Swipe me! + + + ); +} + +const styles = StyleSheet.create({ + rightAction: { width: 50, height: 50, backgroundColor: 'purple' }, + separator: { + width: '100%', + borderTopWidth: 1, + }, + swipeable: { + height: 50, + backgroundColor: 'papayawhip', + alignItems: 'center', + }, +}); +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/touchables.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/touchables.md new file mode 100644 index 0000000000..6d1f19107f --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/touchables.md @@ -0,0 +1,56 @@ +--- +id: touchables +title: Touchables +sidebar_label: Touchables +--- + +:::warning +Touchables will be removed in the future version of Gesture Handler. Use Pressable instead. +::: + +Gesture Handler library provides an implementation of RN's touchable components that are based on [native buttons](buttons.mdx) and does not rely on JS responder system utilized by RN. Our touchable implementation follows the same API and aims to be a drop-in replacement for touchables available in React Native. + +React Native's touchables API can be found here: + +- [Touchable Native Feedback](https://reactnative.dev/docs/touchablenativefeedback) +- [Touchable Highlight](https://reactnative.dev/docs/touchablehighlight) +- [Touchable Opacity](https://reactnative.dev/docs/touchableopacity) +- [Touchable Without Feedback](https://reactnative.dev/docs/touchablewithoutfeedback) + +All major touchable properties (except from `pressRetentionOffset`) have been adopted and should behave in a similar way as with RN's touchables. + +The motivation for using RNGH touchables as a replacement for these imported from React Native is to follow built-in native behavior more closely by utilizing platform native touch system instead of relying on the JS responder system. +These touchables and their feedback behavior are deeply integrated with native +gesture ecosystem and could be connected with other native components (e.g. `ScrollView`) and Gesture Handlers easily and in a more predictable way, which +follows native apps' behavior. + +Our intention was to make switch for these touchables as simple as possible. In order to use RNGH's touchables the only thing you need to do is to change library from which you import touchable components. +need only to change imports of touchables. + +:::info +Gesture Handler's TouchableOpacity uses native driver for animations by default. If this causes problems for you, you can set `useNativeAnimations` prop to false. +::: + +### Example: + +```javascript +import { + TouchableNativeFeedback, + TouchableHighlight, + TouchableOpacity, + TouchableWithoutFeedback, +} from 'react-native'; +``` + +has to be replaced with: + +```javascript +import { + TouchableNativeFeedback, + TouchableHighlight, + TouchableOpacity, + TouchableWithoutFeedback, +} from 'react-native-gesture-handler'; +``` + +For a comparison of both touchable implementations see our [touchables example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/apps/common-app/src/release_tests/touchables/index.tsx) diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/_category_.json b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/_category_.json new file mode 100644 index 0000000000..ea8044f531 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Fundamentals", + "position": 1, + "link": { + "type": "generated-index" + } +} diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/gesture-composition.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/gesture-composition.md new file mode 100644 index 0000000000..31657f617c --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/gesture-composition.md @@ -0,0 +1,408 @@ +--- +id: gesture-composition +title: Gesture composition & interactions +sidebar_label: Gesture composition & interactions +sidebar_position: 3 +--- + +Composing gestures is much simpler in RNGH2, you don't need to create a ref for every gesture that depends on another one. Instead you can use `Race`, `Simultaneous` and `Exclusive` methods provided by the `Gesture` object. + +## Race + +Only one of the provided gestures can become active at the same time. The first gesture to become active will cancel the rest of the gestures. It accepts variable number of arguments. +It is the equivalent to having more than one gesture handler without defining `simultaneousHandlers` and `waitFor` props. + +For example, lets say that you have a component that you want to make draggable but you also want to show additional options on long press. Presumably you would not want the component to move after the long press activates. You can accomplish this using `Race`: + +> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). + +```js +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, + withTiming, +} from 'react-native-reanimated'; + +function App() { + const offset = useSharedValue({ x: 0, y: 0 }); + const start = useSharedValue({ x: 0, y: 0 }); + const popupPosition = useSharedValue({ x: 0, y: 0 }); + const popupAlpha = useSharedValue(0); + + const animatedStyles = useAnimatedStyle(() => { + return { + transform: [ + { translateX: offset.value.x }, + { translateY: offset.value.y }, + ], + }; + }); + + const animatedPopupStyles = useAnimatedStyle(() => { + return { + transform: [ + { translateX: popupPosition.value.x }, + { translateY: popupPosition.value.y }, + ], + opacity: popupAlpha.value, + }; + }); + + const dragGesture = Gesture.Pan() + .onStart((_e) => { + popupAlpha.value = withTiming(0); + }) + .onUpdate((e) => { + offset.value = { + x: e.translationX + start.value.x, + y: e.translationY + start.value.y, + }; + }) + .onEnd(() => { + start.value = { + x: offset.value.x, + y: offset.value.y, + }; + }); + + const longPressGesture = Gesture.LongPress().onStart((_event) => { + popupPosition.value = { x: offset.value.x, y: offset.value.y }; + popupAlpha.value = withTiming(1); + }); + + const composed = Gesture.Race(dragGesture, longPressGesture); + + return ( + + + + + + + ); +} +``` + +## Simultaneous + +All of the provided gestures can activate at the same time. Activation of one will not cancel the other. +It is the equivalent to having some gesture handlers, each with `simultaneousHandlers` prop set to the other handlers. + +For example, if you want to make a gallery app, you might want user to be able to zoom, rotate and pan around photos. You can do it with `Simultaneous`: + +> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). + +```js +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, +} from 'react-native-reanimated'; + +function App() { + const offset = useSharedValue({ x: 0, y: 0 }); + const start = useSharedValue({ x: 0, y: 0 }); + const scale = useSharedValue(1); + const savedScale = useSharedValue(1); + const rotation = useSharedValue(0); + const savedRotation = useSharedValue(0); + const animatedStyles = useAnimatedStyle(() => { + return { + transform: [ + { translateX: offset.value.x }, + { translateY: offset.value.y }, + { scale: scale.value }, + { rotateZ: `${rotation.value}rad` }, + ], + }; + }); + + const dragGesture = Gesture.Pan() + .averageTouches(true) + .onUpdate((e) => { + offset.value = { + x: e.translationX + start.value.x, + y: e.translationY + start.value.y, + }; + }) + .onEnd(() => { + start.value = { + x: offset.value.x, + y: offset.value.y, + }; + }); + + const zoomGesture = Gesture.Pinch() + .onUpdate((event) => { + scale.value = savedScale.value * event.scale; + }) + .onEnd(() => { + savedScale.value = scale.value; + }); + + const rotateGesture = Gesture.Rotation() + .onUpdate((event) => { + rotation.value = savedRotation.value + event.rotation; + }) + .onEnd(() => { + savedRotation.value = rotation.value; + }); + + const composed = Gesture.Simultaneous( + dragGesture, + Gesture.Simultaneous(zoomGesture, rotateGesture) + ); + + return ( + + + + + + ); +} +``` + +## Exclusive + +Only one of the provided gestures can become active, with the first one having a higher priority than the second one (if both gestures are still possible, the second one will wait for the first one to fail before it activates), second one having a higher priority than the third one, and so on. +It is equivalent to having some gesture handlers where the second one has the `waitFor` prop set to the first handler, third one has the `waitFor` prop set to the first and the second one, and so on. + +For example, if you want to make a component that responds to single tap as well as to a double tap, you can accomplish that using `Exclusive`: + +> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). + +```js +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + const singleTap = Gesture.Tap().onEnd((_event, success) => { + if (success) { + console.log('single tap!'); + } + }); + const doubleTap = Gesture.Tap() + .numberOfTaps(2) + .onEnd((_event, success) => { + if (success) { + console.log('double tap!'); + } + }); + + const taps = Gesture.Exclusive(doubleTap, singleTap); + + return ( + + + + ); +} +``` + +# Cross-component interactions + +You may have noticed that gesture composition described above requires you to mount all of the composed gestures under a single `GestureDetector`, effectively attaching them to the same underlying component. You can customize how gestures interact with each other across multiple components in a couple of ways: + +## requireExternalGestureToFail + +`requireExternalGestureToFail` allows to delay activation of the handler until all handlers passed as arguments to this method fail (or don't begin at all). + +For example, you may want to have two nested components, both of them can be tapped by the user to trigger different actions: outer view requires one tap, but the inner one requires 2 taps. If you don't want the first tap on the inner view to activate the outer handler, you must make the outer gesture wait until the inner one fails: + +```jsx +import React from 'react'; +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + Gesture, + GestureHandlerRootView, +} from 'react-native-gesture-handler'; + +export default function Example() { + const innerTap = Gesture.Tap() + .numberOfTaps(2) + .onStart(() => { + console.log('inner tap'); + }); + + const outerTap = Gesture.Tap() + .onStart(() => { + console.log('outer tap'); + }) + .requireExternalGestureToFail(innerTap); + + return ( + + + + + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'center', + }, + outer: { + width: 250, + height: 250, + backgroundColor: 'lightblue', + }, + inner: { + width: 100, + height: 100, + backgroundColor: 'blue', + alignSelf: 'center', + }, +}); +``` + +## blocksExternalGesture + +`blocksExternalGesture` works similarly to `requireExternalGestureToFail` but the direction of the relation is reversed - instead of being one-to-many relation, it's many-to-one. It's especially useful for making lists where the `ScrollView` component needs to wait for every gesture underneath it. All that's required to do is to pass a ref, for example: + +```jsx +import React, { useRef } from 'react'; +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + Gesture, + GestureHandlerRootView, + ScrollView, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, + withTiming, +} from 'react-native-reanimated'; + +const ITEMS = ['red', 'green', 'blue', 'yellow']; + +function Item({ backgroundColor, scrollRef }) { + const scale = useSharedValue(1); + const zIndex = useSharedValue(1); + + const pinch = Gesture.Pinch() + .blocksExternalGesture(scrollRef) + .onBegin(() => { + zIndex.value = 100; + }) + .onChange((e) => { + scale.value *= e.scaleChange; + }) + .onFinalize(() => { + scale.value = withTiming(1, undefined, (finished) => { + if (finished) { + zIndex.value = 1; + } + }); + }); + + const animatedStyles = useAnimatedStyle(() => ({ + transform: [{ scale: scale.value }], + zIndex: zIndex.value, + })); + + return ( + + + + ); +} + +export default function Example() { + const scrollRef = useRef(); + + return ( + + + {ITEMS.map((item) => ( + + ))} + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + }, + item: { + flex: 1, + aspectRatio: 1, + }, +}); +``` + +## simultaneousWithExternalGesture + +`simultaneousWithExternalGesture` allows gestures across different components to be recognized simultaneously. For example, you may want to have two nested views, both with tap gesture attached. Both of them require one tap, but tapping the inner one should also activate the gesture attached to the outer view: + +```jsx +import React from 'react'; +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + Gesture, + GestureHandlerRootView, +} from 'react-native-gesture-handler'; + +export default function Example() { + const innerTap = Gesture.Tap() + .onStart(() => { + console.log('inner tap'); + }); + + const outerTap = Gesture.Tap() + .onStart(() => { + console.log('outer tap'); + }) + .simultaneousWithExternalGesture(innerTap); + + return ( + + + + + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'center', + }, + outer: { + width: 250, + height: 250, + backgroundColor: 'lightblue', + }, + inner: { + width: 100, + height: 100, + backgroundColor: 'blue', + alignSelf: 'center', + }, +}); +``` \ No newline at end of file diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/installation.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/installation.md new file mode 100644 index 0000000000..1764de7cd0 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/installation.md @@ -0,0 +1,177 @@ +--- +id: installation +title: Installation +sidebar_position: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Requirements + +`react-native-gesture-handler` supports the three latest minor releases of `react-native`. + +| version | `react-native` version | +| ------- | ---------------------- | +| 2.28.0+ | 0.79.0+ | +| 2.26.0+ | 0.78.0+ | +| 2.25.0+ | 0.76.0+ | +| 2.24.0+ | 0.75.0+ | +| 2.21.0+ | 0.74.0+ | +| 2.18.0+ | 0.73.0+ | +| 2.16.0+ | 0.68.0+ | +| 2.14.0+ | 0.67.0+ | +| 2.10.0+ | 0.64.0+ | +| 2.0.0+ | 0.63.0+ | + +In order to fully utilize the [touch events](/docs/gestures/touch-events/) you also need to use `react-native-reanimated` 2.3.0 or newer. + +Setting up `react-native-gesture-handler` is pretty straightforward: + +### 1. Start with installing the package from npm: + + + + ```bash + npx expo install react-native-gesture-handler + ``` + + + ```bash + npm install react-native-gesture-handler + ``` + + + ```bash + yarn add react-native-gesture-handler + ``` + + + +### 2. Wrap your app with `GestureHandlerRootView` component + +```jsx +import { GestureHandlerRootView } from 'react-native-gesture-handler'; + +export default function App() { + return ( + + + + ); +} +``` + +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. 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. 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'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. + +:::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. +::: + +:::tip +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. +::: + +### 3. Platform specific setup + +#### [Expo development build](https://docs.expo.dev/develop/development-builds/introduction/) + +When using an Expo development build, run prebuild to update the native code in the ios and android directories. + +```bash +npx expo prebuild +``` + +#### Android + +Setting up Gesture Handler on Android doesn't require any more steps. Keep in mind that if you want to use gestures in Modals you need to wrap Modal's content with `GestureHandlerRootView`: + +```jsx +import { Modal } from 'react-native'; +import { GestureHandlerRootView } from 'react-native-gesture-handler'; + +export function CustomModal({ children, ...rest }) { + return ( + + {children} + + ); +} +``` + +##### Kotlin + +Gesture Handler on Android is implemented in Kotlin. If you need to set a specific Kotlin version to be used by the library, set the `kotlinVersion` ext property in `android/build.gradle` file and RNGH will use that version: + +```groovy +buildscript { + ext { + kotlinVersion = "1.6.21" + } +} +``` + +#### iOS + +While developing for iOS, make sure to install [pods](https://cocoapods.org/) first before running the app: + +```bash +cd ios && pod install && cd .. +``` + +#### Web + +There is no additional configuration required for the web. + +#### With [wix/react-native-navigation](https://github.com/wix/react-native-navigation) + +If you are using a native navigation library like [wix/react-native-navigation](https://github.com/wix/react-native-navigation) you need to make sure that every screen is wrapped with `GestureHandlerRootView`. This can be done for example at the stage when you register your screens. Here's an example: + +```js +import { Navigation } from 'react-native-navigation'; +import FirstTabScreen from './FirstTabScreen'; +import SecondTabScreen from './SecondTabScreen'; +import PushedScreen from './PushedScreen'; +// register all screens of the app (including internal ones) +export function registerScreens() { + Navigation.registerComponent( + 'example.FirstTabScreen', + () => { + return ( + + + + ); + }, + () => FirstTabScreen + ); + Navigation.registerComponent( + 'example.SecondTabScreen', + () => { + return ( + + + + ); + }, + () => SecondTabScreen + ); + Navigation.registerComponent( + 'example.PushedScreen', + () => { + return ( + + + + ); + }, + () => PushedScreen + ); +} +``` + +You can check out [this example project](https://github.com/henrikra/nativeNavigationGestureHandler) to see this kind of set up in action. + +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. diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/introduction.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/introduction.md new file mode 100644 index 0000000000..f7dc0376d9 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/introduction.md @@ -0,0 +1,122 @@ +--- +id: introduction +title: Introduction +sidebar_label: Introduction +sidebar_position: 1 +slug: / +--- + +Gesture Handler provides a declarative API exposing the native platform's touch and gesture system to React Native. It's designed to be a replacement of React Native's built in touch system called [Gesture Responder System](http://reactnative.dev/docs/gesture-responder-system). Using native touch handling allows to address the performance limitations of React Native's Gesture Responder System. It also provides more control over the platform's native components that can handle gestures on their own. If you want to learn more, we recommend [this talk](https://www.youtube.com/watch?v=V8maYc4R2G0) by [Krzysztof Magiera](https://twitter.com/kzzzf) in which he explains issues with the responder system. + +The main benefits of using React Native Gesture Handler are: + +- A way to use a platform's native touch handling system for recognizing gestures (like pinch, rotation, pan and a few others). +- The ability to define relations between gestures to ensure gestures, and possibly native components, will not conflict with each other. +- Mechanisms to use touchable components that run in native thread and follow platform default behavior; e.g. in the event they are in a scrollable component, turning into pressed state is slightly delayed to prevent it from highlighting when you fling. +- Close integration with [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/) to process touch events on the UI thread. +- Support for different input devices like touch screens, pens and mice. +- Ability to include any native component into the Gesture Handler's touch system, making it work alongside your gestures. + +:::info +We recommended to use Reanimated to implement gesture-driven animations with Gesture Handler. Its more advanced features rely heavily on worklets and the UI runtime provided by Reanimated. +::: + +## Learning resources + +### Apps + +[Gesture Handler Example App](https://github.com/software-mansion/react-native-gesture-handler/tree/main/apps/expo-example) – official gesture handler "showcase" app. + +### Talks and workshops + +[Declarative future of gestures and animations in React Native](https://www.youtube.com/watch?v=kdq4z2708VM) by [Krzysztof Magiera](https://twitter.com/kzzzf) - talk that explains motivation behind creating gesture handler library. It also presents [react-native-reanimated](https://github.com/software-mansion/react-native-reanimated) and how and when it can be used with gesture handler. + +[React Native workshop with Expo team @ReactEurope 2018](https://youtu.be/JSIoE_ReeDk?t=41m49s) by [Brent Vatne](https://twitter.com/notbrent) – great workshop explaining gesture handler in details and presenting a few exercises that will help get you started. + +[Living in an async world of React Native](https://www.youtube.com/watch?v=-Izgons3mec) by [Krzysztof Magiera](https://twitter.com/kzzzf) – talk which highlights some issue with the React Native's touch system Gesture Handler aims to address. Also the motivation for building this library is explained. + +[React Native Touch & Gesture](https://www.youtube.com/watch?v=V8maYc4R2G0) by [Krzysztof Magiera](https://twitter.com/kzzzf) - talk explaining JS responder system limitations and points out some of the core features of Gesture Handler. + +## Contributing + +If you are interested in the project and want to contribute or support it in other ways don't hesitate to contact anyone from the team on Twitter or Bluesky (links below)! + +All PRs are welcome, but talk to us before you start working on something big. + +The easiest way to get started with contributing code is by: + +- Reviewing the list of [open issues](https://github.com/software-mansion/react-native-gesture-handler/issues) and trying to solve the one that seem approachable to you. +- Updating the [documentation](https://github.com/software-mansion/react-native-gesture-handler/blob/main/docs) whenever you see some information is unclear, missing or out of date. + +Code is only one way how you can contribute. You may want to consider [replying on issues](https://github.com/software-mansion/react-native-gesture-handler/issues) if you know how to help. + +## Community + +We are very proud of the community that has been build around this package. We really appreciate all your help regardless of it is a pull request, issue report, helping others by commenting on existing issues or posting some demo or video tutorial on social media. +If you've build something with this library you'd like to share, please contact us as we'd love to help share it with others. + +### Gesture Handler Team 🚀 + +
+ +
+
+ +
+
Jakub Piasecki
+ + +
+ +
+
+ +
+
Michał Bert
+ +
+ +
+
+ +
+
Ignacy Łątka
+ +
+ +
+
+ +
+
Krzysztof Magiera
+ + +
+ +
+ +### Sponsors + +We really appreciate our sponsors! Thanks to them we can develop our library and make the react-native world a better place. Special thanks for: + + diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/states-events.mdx b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/states-events.mdx new file mode 100644 index 0000000000..26df3bcd92 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/states-events.mdx @@ -0,0 +1,89 @@ +--- +id: states-events +title: Gesture states & events +sidebar_label: Gesture states & events +sidebar_position: 4 +--- + +Every gesture can be treated as ["state machine"](https://en.wikipedia.org/wiki/Finite-state_machine). +At any given time, each handler instance has an assigned state that can change when new touch events occur or can be forced to change by the touch system in certain circumstances. + +A gesture can be in one of the six possible states: + +- #### UNDETERMINED + + This is the initial state of each gesture recognizer and it goes into this state after it's done recognizing a gesture. + +- #### FAILED + + A gesture recognizer received some touches but for some reason didn't recognize them. For example, if a finger travels more distance than a defined `maxDist` property allows, then the gesture won't become active but will fail instead. Afterwards, it's state will be reset to `UNDETERMINED`. + +- #### BEGAN + + Gesture recognizer has started receiving touch stream but hasn't yet received enough data to either [fail](#failed) or [activate](#active). + +- #### CANCELLED + + The gesture recognizer has received a signal (possibly new touches or a command from the touch system controller) resulting in the cancellation of a continuous gesture. The gesture's state will become `CANCELLED` until it is finally reset to the initial state, `UNDETERMINED`. + +- #### ACTIVE + + Recognizer has recognized a gesture. It will become and stay in the `ACTIVE` state until the gesture finishes (e.g. when user lifts the finger) or gets cancelled by the touch system. Under normal circumstances the state will then turn into `END`. In the case that a gesture is cancelled by the touch system, its state would then become `CANCELLED`. + +- #### END + + The gesture recognizer has received touches signalling the end of a gesture. Its state will become `END` until it is reset to `UNDETERMINED`. + +## State flows + +The most typical flow of state is when a gesture picks up on an initial touch event, then recognizes it, then acknowledges its ending and resets itself back to the initial state. + +The flow looks as follows: + +import GestureStateFlowExample from '@site/src/examples/GestureStateFlowExample'; + +} + label="Drag or long-press the circle" + larger={true} +/> + +## Events + +There are three types of events in RNGH2: `StateChangeEvent`, `GestureEvent` and `PointerEvent`. The `StateChangeEvent` is send every time a gesture moves to a different state, while `GestureEvent` is send every time a gesture is updated. The first two carry a gesture-specific data and a `state` property, indicating the current state of the gesture. `StateChangeEvent` also carries a `oldState` property indicating the previous state of the gesture. `PointerEvent` carries information about raw touch events, like touching the screen or moving the finger. These events are handled internally before they are passed along to the correct callbacks: + +### `onBegin` + +Is called when a gesture transitions to the [`BEGAN`](#began) state. + +### `onStart` + +Is called when a gesture transitions to the [`ACTIVE`](#active) state. + +### `onEnd` + +Is called when a gesture transitions from the [`ACTIVE`](#active) state to the [`END`](#end), [`FAILED`](#failed), or [`CANCELLED`](#cancelled) state. If the gesture transitions to the [`END`](#end) state, the `success` argument is set to `true` otherwise it is set to `false`. + +### `onFinalize` + +Is called when a gesture transitions to the [`END`](#end), [`FAILED`](#failed), or [`CANCELLED`](#cancelled) state. If the gesture transitions to the [`END`](#end) state, the `success` argument is set to `true` otherwise it is set to `false`. If the gesture transitions from the [`ACTIVE`](#active) state, it will be called after `onEnd`. + +### `onUpdate` + +Is called every time a gesture is updated while it is in the [`ACTIVE`](#active) state. + +### `onPointerDown` + +Is called when new pointers are placed on the screen. It may carry information about more than one pointer because the events are batched. + +### `onPointerMove` + +Is called when pointers are moved on the screen. It may carry information about more than one pointer because the events are batched. + +### `onPointerUp` + +Is called when pointers are lifted from the screen. It may carry information about more than one pointer because the events are batched. + +### `onPointerCancelled` + +Is called when there will be no more information about this pointer. It may be called because the gesture has ended or was interrupted. It may carry information about more than one pointer because the events are batched. diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/_category_.json b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/_category_.json similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/_category_.json rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/_category_.json diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/about-handlers.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/about-handlers.md similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/about-handlers.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/about-handlers.md diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/common-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/common-gh.md similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/common-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/common-gh.md diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/create-native-wrapper.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/create-native-wrapper.md similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/create-native-wrapper.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/create-native-wrapper.md diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/fling-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/fling-gh.md similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/fling-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/fling-gh.md diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/force-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/force-gh.md similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/force-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/force-gh.md diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/interactions.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/interactions.md similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/interactions.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/interactions.md diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/longpress-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/longpress-gh.md similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/longpress-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/longpress-gh.md diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/nativeview-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/nativeview-gh.md similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/nativeview-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/nativeview-gh.md diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/pan-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pan-gh.md similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/pan-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pan-gh.md diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/pinch-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pinch-gh.md similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/pinch-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pinch-gh.md diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/rotation-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/rotation-gh.md similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/rotation-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/rotation-gh.md diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/tap-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/tap-gh.md similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/tap-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/tap-gh.md diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_category_.json b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_category_.json new file mode 100644 index 0000000000..26dbe96e2b --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Gestures", + "position": 3, + "link": { + "type": "generated-index" + } +} diff --git a/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-callbacks.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-callbacks.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-callbacks.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-callbacks.md diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-config.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-config.md similarity index 74% rename from packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-config.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-config.md index af148874b5..71ca8db252 100644 --- a/packages/docs-gesture-handler/docs/hooks/_shared/base-continuous-gesture-config.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-config.md @@ -1,9 +1,5 @@ ### Properties common to all continuous gestures: -### manualActivation - -```ts -manualActivation: boolean | SharedValue; -``` +### `manualActivation(value: boolean)` When `true` the handler will not activate by itself even if its activation criteria are met. Instead you can manipulate its state using [state manager](/docs/gestures/state-manager/). diff --git a/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-callbacks.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-callbacks.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-callbacks.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-callbacks.md diff --git a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-config.md similarity index 75% rename from packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-config.md index 9484d5194d..2e2fb6d425 100644 --- a/packages/docs-gesture-handler/docs/hooks/_shared/base-gesture-config.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-config.md @@ -1,48 +1,19 @@ ### Properties common to all gestures: -### enabled - -```ts -enabled: boolean | SharedValue; -``` +### `enabled(value: boolean)` Indicates whether the given handler should be analyzing stream of touch events or not. When set to `false` we can be sure that the handler's state will **never** become [`ACTIVE`](/docs/fundamentals/states-events#active). If the value gets updated while the handler already started recognizing a gesture, then the handler's state it will immediately change to [`FAILED`](/docs/fundamentals/states-events#failed) or [`CANCELLED`](/docs/fundamentals/states-events#cancelled) (depending on its current state). Default value is `true`. -### shouldCancelWhenOutside - -```ts -shouldCancelWhenOutside: boolean | SharedValue; -``` +### `shouldCancelWhenOutside(value: boolean)` When `true` the handler will [cancel](/docs/fundamentals/states-events#cancelled) or [fail](/docs/fundamentals/states-events#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. Default value of this property is different depending on the handler type. -Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGesture`](/docs/hooks/use-long-press-gesture) and [`TapGesture`](/docs/hooks/use-tap-gesture) which default to `true`. - -### hitSlop - -```ts -hitSlop: HitSlop | SharedValue; -``` - -```ts -type HitSlop = - | number - | null - | undefined - | Partial< - Record< - 'left' | 'right' | 'top' | 'bottom' | 'vertical' | 'horizontal', - number - > - > - | Record<'width' | 'left', number> - | Record<'width' | 'right', number> - | Record<'height' | 'top', number> - | Record<'height' | 'bottom', number>; -``` +Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGesture`](/docs/gestures/long-press-gesture) and [`TapGesture`](/docs/gestures/tap-gesture) which default to `true`. + +### `hitSlop(settings)` This parameter enables control over what part of the connected view area can be used to [begin](/docs/fundamentals/states-events#began) recognizing the gesture. When a negative number is provided the bounds of the view will reduce the area by the given number of points in each of the sides evenly. @@ -56,65 +27,42 @@ Specifying `width` or `height` is useful if we only want the gesture to activate **IMPORTANT:** Note that this parameter is primarily designed to reduce the area where gesture can activate. Hence it is only supported for all the values (except `width` and `height`) to be non positive (0 or lower). Although on Android it is supported for the values to also be positive and therefore allow to expand beyond view bounds but not further than the parent view bounds. To achieve this effect on both platforms you can use React Native's View [hitSlop](https://reactnative.dev/docs/view.html#hitslop) property. -### testID +### `withRef(ref)` -```ts -testID: string; -``` +Sets a ref to the gesture object, allowing for interoperability with the old +API. -Sets a `testID` property for gesture object, allowing for querying for it in tests. +### `withTestId(testID)` -### cancelsTouchesInView (**iOS only**) +Sets a `testID` property for gesture object, allowing for querying for it in tests. -```ts -cancelsTouchesInView: boolean | SharedValue; -``` +### `cancelsTouchesInView(value)` (**iOS only**) Accepts a boolean value. When `true`, the gesture will cancel touches for native UI components (`UIButton`, `UISwitch`, etc) it's attached to when it becomes [`ACTIVE`](/docs/fundamentals/states-events#active). Default value is `true`. -### runOnJS - -```ts -runOnJS: boolean | SharedValue; -``` +### `runOnJS(value: boolean)` When `react-native-reanimated` is installed, the callbacks passed to the gestures are automatically workletized and run on the UI thread when called. This option allows for changing this behavior: when `true`, all the callbacks will be run on the JS thread instead of the UI thread, regardless of whether they are worklets or not. Defaults to `false`. -### simultaneousWith - -```ts -simultaneousWith: Gesture | Gesture[] -``` +### `simultaneousWithExternalGesture(otherGesture1, otherGesture2, ...)` Adds a gesture that should be recognized simultaneously with this one. **IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](/docs/fundamentals/gesture-composition). [`GestureDetector`](/docs/gestures/gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. -### requireToFail - -```ts -requireToFail: Gesture | Gesture[] -``` +### `requireExternalGestureToFail(otherGesture1, otherGesture2, ...)` Adds a relation requiring another gesture to fail, before this one can activate. -### block - -```ts -block: Gesture | Gesture[] -``` +### `blocksExternalGesture(otherGesture1, otherGesture2, ...)` Adds a relation that makes other gestures wait with activation until this gesture fails (or doesn't start at all). **IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](/docs/fundamentals/gesture-composition).[`GestureDetector`](/docs/gestures/gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. -### activeCursor - -```ts -activeCursor: ActiveCursor | SharedValue; -``` +### `activeCursor(value)` (Web only) -This parameter allows to specify which cursor should be used when gesture activates. Supports all [CSS cursor values](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/cursor#keyword) (e.g. `"grab"`, `"zoom-in"`). Default value is set to `"auto"`. +This parameter allows to specify which cursor should be used when gesture activates. Supports all CSS cursor values (e.g. `"grab"`, `"zoom-in"`). Default value is set to `"auto"`. diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-event-data.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-event-data.md new file mode 100644 index 0000000000..6d6767d639 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-event-data.md @@ -0,0 +1,19 @@ +### Event attributes common to all gestures: + +### `state` + +Current [state](/docs/fundamentals/states-events) of the handler. Expressed as one of the constants exported under `State` object by the library. + +### `numberOfPointers` + +Represents the number of pointers (fingers) currently placed on the screen. + +### `pointerType` + +Indicates the type of pointer device in use. This value is represented by the `PointerType` enum, which includes the following fields: + +- `TOUCH` - represents finger +- `STYLUS` - represents stylus or digital pen +- `MOUSE` - represents computer mouse +- `KEY` - represents keyboard +- `OTHER` - represents unknown device type that is not relevant diff --git a/packages/docs-gesture-handler/docs/gestures/_shared/gesture-detector-functional1.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/gesture-detector-functional1.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/_shared/gesture-detector-functional1.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/gesture-detector-functional1.md diff --git a/packages/docs-gesture-handler/docs/gestures/composed-gestures.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/composed-gestures.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/composed-gestures.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/composed-gestures.md diff --git a/packages/docs-gesture-handler/docs/gestures/fling-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/fling-gesture.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/fling-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/fling-gesture.md diff --git a/packages/docs-gesture-handler/docs/gestures/force-touch-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/force-touch-gesture.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/force-touch-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/force-touch-gesture.md diff --git a/packages/docs-gesture-handler/docs/gestures/gesture-detector.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture-detector.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/gesture-detector.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture-detector.md diff --git a/packages/docs-gesture-handler/docs/gestures/gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture.md diff --git a/packages/docs-gesture-handler/docs/gestures/hover-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/hover-gesture.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/hover-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/hover-gesture.md diff --git a/packages/docs-gesture-handler/docs/gestures/long-press-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/long-press-gesture.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/long-press-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/long-press-gesture.md diff --git a/packages/docs-gesture-handler/docs/gestures/manual-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/manual-gesture.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/manual-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/manual-gesture.md diff --git a/packages/docs-gesture-handler/docs/gestures/native-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/native-gesture.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/native-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/native-gesture.md diff --git a/packages/docs-gesture-handler/docs/gestures/pan-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/pan-gesture.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/pan-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/pan-gesture.md diff --git a/packages/docs-gesture-handler/docs/gestures/pinch-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/pinch-gesture.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/pinch-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/pinch-gesture.md diff --git a/packages/docs-gesture-handler/docs/gestures/rotation-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/rotation-gesture.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/rotation-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/rotation-gesture.md diff --git a/packages/docs-gesture-handler/docs/gestures/state-manager.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/state-manager.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/state-manager.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/state-manager.md diff --git a/packages/docs-gesture-handler/docs/gestures/tap-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/tap-gesture.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/tap-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/tap-gesture.md diff --git a/packages/docs-gesture-handler/docs/gestures/touch-events.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/touch-events.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/touch-events.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/touch-events.md diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/_category_.json b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/_category_.json new file mode 100644 index 0000000000..b07efb99a5 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Guides", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step1.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step1.md new file mode 100644 index 0000000000..4c6331c1c8 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step1.md @@ -0,0 +1,7 @@ +```jsx +interface Pointer { + visible: boolean; + x: number; + y: number; +} +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step2.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step2.md new file mode 100644 index 0000000000..40079ee2bd --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step2.md @@ -0,0 +1,41 @@ +```jsx +import { StyleSheet } from 'react-native'; +import Animated, { + useAnimatedStyle, + useSharedValue, +} from 'react-native-reanimated'; + +function PointerElement(props: { + pointer: Animated.SharedValue, + active: Animated.SharedValue, +}) { + const animatedStyle = useAnimatedStyle(() => ({ + transform: [ + { translateX: props.pointer.value.x }, + { translateY: props.pointer.value.y }, + { + scale: + (props.pointer.value.visible ? 1 : 0) * + (props.active.value ? 1.3 : 1), + }, + ], + backgroundColor: props.active.value ? 'red' : 'blue', + })); + + return ; +} + +// ... + +const styles = StyleSheet.create({ + pointer: { + width: 60, + height: 60, + borderRadius: 30, + backgroundColor: 'red', + position: 'absolute', + marginStart: -30, + marginTop: -30, + }, +}); +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step3.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step3.md new file mode 100644 index 0000000000..4486b0a123 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step3.md @@ -0,0 +1,31 @@ +```jsx +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; + +export default function Example() { + const trackedPointers: Animated.SharedValue[] = []; + const active = useSharedValue(false); + + for (let i = 0; i < 12; i++) { + trackedPointers[i] = + useSharedValue < + Pointer > + { + visible: false, + x: 0, + y: 0, + }; + } + + const gesture = Gesture.Manual(); + + return ( + + + {trackedPointers.map((pointer, index) => ( + + ))} + + + ); +} +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step4.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step4.md new file mode 100644 index 0000000000..36ec2c34bd --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step4.md @@ -0,0 +1,15 @@ +```jsx {2-15} +const gesture = Gesture.Manual().onTouchesDown((e, manager) => { + for (const touch of e.changedTouches) { + trackedPointers[touch.id].value = { + visible: true, + x: touch.x, + y: touch.y, + }; + } + + if (e.numberOfTouches >= 2) { + manager.activate(); + } +}); +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step5.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step5.md new file mode 100644 index 0000000000..d2f9377cc8 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step5.md @@ -0,0 +1,13 @@ +```jsx {3-12} +const gesture = Gesture.Manual() + ... + .onTouchesMove((e, _manager) => { + for (const touch of e.changedTouches) { + trackedPointers[touch.id].value = { + visible: true, + x: touch.x, + y: touch.y, + }; + } + }) +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step6.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step6.md new file mode 100644 index 0000000000..323f9516cb --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step6.md @@ -0,0 +1,17 @@ +```jsx {3-16} +const gesture = Gesture.Manual() + ... + .onTouchesUp((e, manager) => { + for (const touch of e.changedTouches) { + trackedPointers[touch.id].value = { + visible: false, + x: touch.x, + y: touch.y, + }; + } + + if (e.numberOfTouches === 0) { + manager.end(); + } + }) +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step7.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step7.md new file mode 100644 index 0000000000..913e766ae8 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/_steps/step7.md @@ -0,0 +1,10 @@ +```jsx {3-10} +const gesture = Gesture.Manual() + ... + .onStart(() => { + active.value = true; + }) + .onEnd(() => { + active.value = false; + }); +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/index.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/index.md new file mode 100644 index 0000000000..6d17988d18 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/manual-gestures/index.md @@ -0,0 +1,62 @@ +--- +id: manual-gestures +title: Manual gestures +sidebar_label: Manual gestures +sidebar_position: 2 +--- + +import Step, { Divider } from '@site/src/theme/Step'; +import Step1 from './\_steps/step1.md'; +import Step2 from './\_steps/step2.md'; +import Step3 from './\_steps/step3.md'; +import Step4 from './\_steps/step4.md'; +import Step5 from './\_steps/step5.md'; +import Step6 from './\_steps/step6.md'; +import Step7 from './\_steps/step7.md'; + +RNGH2 finally brings one of the most requested features: manual gestures and touch events. To demonstrate how to make a manual gesture we will make a simple one that tracks all pointers on the screen. + + + First, we need a way to store information about the pointer: whether it should be visible and its position. + + + + + We also need a component to mark where a pointer is. In order to accomplish that we will make a component that accepts two shared values: one holding information about the pointer using the interface we just created, the other holding a bool indicating whether the gesture has activated. + In this example when the gesture is not active, the ball representing it will be blue and when it is active the ball will be red and slightly bigger. + + + + + Now we have to make a component that will handle the gesture and draw all the pointer indicators. We will store data about pointers in an array of size 12 as that is the maximum number of touches that RNGH will track, and render them inside an Animated.View. + + + + + We have our components set up and we can finally get to making the gesture! We will start with onTouchesDown where we need to set position of the pointers and make them visible. We can get this information from the touches property of the event. In this case we will also check how many pointers are on the screen and activate the gesture if there are at least two. + + + + + Next, we will handle pointer movement. In onTouchesMove we will simply update the position of moved pointers. + + + + + We also need to handle lifting fingers from the screen, which corresponds to onTouchesUp. Here we will just hide the pointers that were lifted and end the gesture if there are no more pointers on the screen. + Note that we are not handling onTouchesCancelled as in this very basic case we don't expect it to happen, however you should clear data about cancelled pointers (most of the time all active ones) when it is called. + + + + + Now that our pointers are being tracked correctly and we have the state management, we can handle activation and ending of the gesture. In our case, we will simply set the active shared value either to true or false. + + + +And that's all! As you can see using manual gestures is really easy but as you can imagine, manual gestures are a powerful tool that makes it possible to accomplish things that were previously impossible with RNGH. + +## Modifying existing gestures + +While manual gestures open great possibilities we are aware that reimplementing pinch or rotation from scratch just because you need to activate in specific circumstances or require position of the fingers, would be a waste of time as those gestures are already available. Therefore, you can use touch events with every gesture to extract more detailed information about the gesture than what the basic events alone provide. We also added a `manualActivation` modifier on all continuous gestures, which prevents the gesture it is applied to from activating automatically, giving you full control over its behavior. + +This functionality makes another highly requested feature possible: drag after long press. Simply set `manualActivation` to `true` on a `PanGesture` and use `StateManager` to fail the gesture if the user attempts to drag the component sooner than the duration of the long press. diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/migrating-off-rnghenabledroot.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/migrating-off-rnghenabledroot.md new file mode 100644 index 0000000000..b777549b33 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/migrating-off-rnghenabledroot.md @@ -0,0 +1,49 @@ +--- +id: migrating-off-rnghenabledroot +title: Migrating off RNGHEnabledRootView +--- + +## Update `MainActivity.java` + +Update your `MainActivity.java` file (or wherever you create an instance of `ReactActivityDelegate`), so that it no longer overrides the method responsible for creating `ReactRootView` instance, or modify it so that it no longer uses `RNGestureHandlerEnabledRootView`. Do not forget to remove import for `RNGestureHandlerEnabledRootView`: + +```java +package com.swmansion.gesturehandler.react.example; + +import com.facebook.react.ReactActivity; +- import com.swmansion.gesturehandler.react.RNGestureHandlerEnabledRootView; +public class MainActivity extends ReactActivity { + +- @Override +- protected ReactActivityDelegate createReactActivityDelegate() { +- return new ReactActivityDelegate(this, getMainComponentName()) { +- @Override +- protected ReactRootView createRootView() { +- return new RNGestureHandlerEnabledRootView(MainActivity.this); +- } +- }; +- } +} +``` + +## Check if your app works correctly + +Some libraries (for example React Navigation) already use `GestureHandlerRootView` as a wrapper to enable gesture interactions. In that case you don't have to add one yourself. If gestures in your app work as expected after removing `RNGestureHandlerEnabledRootView` you can skip the next step. + +## Update your JS code + +Instead of using `RNGestureHandlerEnabledRootView` wrap your entry point with ``, for example: + +```jsx +export default function App() { + return ( + + {/* content */} + + ); +} +``` + +:::info +Note that `GestureHandlerRootView` acts like a normal `View`. So if you want it to fill the screen, you will need to pass `{ flex: 1 }` like you'll need to do with a normal View. By default, it'll take the size of the content nested inside. +::: diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step1.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step1.md new file mode 100644 index 0000000000..6e5c8de76b --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step1.md @@ -0,0 +1,13 @@ +```jsx +import { StyleSheet } from 'react-native'; + +const styles = StyleSheet.create({ + ball: { + width: 100, + height: 100, + borderRadius: 100, + backgroundColor: 'blue', + alignSelf: 'center', + }, +}); +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step2.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step2.md new file mode 100644 index 0000000000..7292504d92 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step2.md @@ -0,0 +1,12 @@ +```jsx +import { GestureDetector } from 'react-native-gesture-handler'; +import Animated from 'react-native-reanimated'; + +function Ball() { + return ( + + + + ); +} +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step3.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step3.md new file mode 100644 index 0000000000..ac49f59bd9 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step3.md @@ -0,0 +1,25 @@ +```jsx +import { + useSharedValue, + useAnimatedStyle, + withSpring, +} from 'react-native-reanimated'; + +function Ball() { + const isPressed = useSharedValue(false); + const offset = useSharedValue({ x: 0, y: 0 }); + + const animatedStyles = useAnimatedStyle(() => { + return { + transform: [ + { translateX: offset.value.x }, + { translateY: offset.value.y }, + { scale: withSpring(isPressed.value ? 1.2 : 1) }, + ], + backgroundColor: isPressed.value ? 'yellow' : 'blue', + }; + }); + + // ... +} +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step4.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step4.md new file mode 100644 index 0000000000..7750e97e3b --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step4.md @@ -0,0 +1,9 @@ +```jsx {4} +// ... +return ( + + + +); +// ... +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step5.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step5.md new file mode 100644 index 0000000000..a2ab8eb776 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/_steps/step5.md @@ -0,0 +1,38 @@ +```jsx +import { Gesture } from 'react-native-gesture-handler'; + +function Ball() { + // ... + const start = useSharedValue({ x: 0, y: 0 }); + const gesture = Gesture.Pan() + .onBegin(() => { + isPressed.value = true; + }) + .onUpdate((e) => { + offset.value = { + x: e.translationX + start.value.x, + y: e.translationY + start.value.y, + }; + }) + .onEnd(() => { + start.value = { + x: offset.value.x, + y: offset.value.y, + }; + }) + .onFinalize(() => { + isPressed.value = false; + }); + // ... +} +``` + +```jsx {3} +// ... +return ( + + + +); +// ... +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/index.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/index.md new file mode 100644 index 0000000000..555fde1258 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/quickstart/index.md @@ -0,0 +1,56 @@ +--- +id: quickstart +title: Quick start +sidebar_label: Quick start +sidebar_position: 1 +--- + +import Step, { Divider } from '@site/src/theme/Step'; +import Step1 from './\_steps/step1.md'; +import Step2 from './\_steps/step2.md'; +import Step3 from './\_steps/step3.md'; +import Step4 from './\_steps/step4.md'; +import Step5 from './\_steps/step5.md'; + +RNGH2 provides much simpler way to add gestures to your app. All you need to do is wrap the view that you want your gesture to work on with [`GestureDetector`](/docs/gestures/gesture-detector), define the gesture and pass it to detector. That's all! + +To demonstrate how you would use the new API, let's make a simple app where you can drag a ball around. You will need to add `react-native-gesture-handler` (for gestures) and `react-native-reanimated` (for animations) modules. + + +
First let's define styles we will need to make the app:
+ + + + +
Then we can start writing our Ball component:
+ + + + +
+ We also need to define{' '} + + shared values + {' '} + to keep track of the ball position and create animated styles in order to be + able to position the ball on the screen: +
+ + + + +
And add it to the ball's styles:
+ + + + +
+ The only thing left is to define the pan gesture and assign it to the + detector: +
+ + + +Note the `start` shared value. We need it to store the position of the ball at the moment we grab it to be able to correctly position it later, because we only have access to translation relative to the starting point of the gesture. + +Now you can just add `Ball` component to some view in the app and see the results! (Or you can just check the code [here](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/new_api/velocityTest/index.tsx) and see it in action in the Example app.) diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/swipe-and-scroll.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/swipe-and-scroll.md new file mode 100644 index 0000000000..b6d2f79bd7 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/swipe-and-scroll.md @@ -0,0 +1,13 @@ +--- +id: swipe-and-scroll +title: Custom swipeable components inside ScrollView (web) +sidebar_position: 5 +--- + +While we recommend using our own [`ReanimatedSwipeable`](../components/reanimated_swipeable.md) component, creating your own version of swipeable gives you more control over its behavior. Common issue here is that after creating your own swipeable component, scroll does not work. In that case, try adding [`touchAction`](../gestures/gesture-detector.md#touchaction-web-only) set to `"pan-y"`, like this: + +```jsx + + ... + +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/testing.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/testing.md new file mode 100644 index 0000000000..7a8f3bc49a --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/testing.md @@ -0,0 +1,129 @@ +--- +id: testing +title: Testing with Jest +sidebar_position: 4 +--- + +## Mocking native modules + +In order to load mocks provided by RNGH add following to your jest config in `package.json`: + +```json +"setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"] +``` + +Example: + +```json +"jest": { + "preset": "react-native", + "setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"] +} +``` + +## Testing Gestures' and Gesture handlers' callbacks + +RNGH provides an API for triggering selected handlers: + +- [`fireGestureHandler(gestureOrHandler, eventList)`](/docs/guides/testing#firegesturehandlergestureorhandler-eventlist) +- [`getByGestureTestId(testID)`](/docs/guides/testing#getbygesturetestidtestid) + +## fireGestureHandler(gestureOrHandler, eventList) + +Simulates one event stream (i.e. event sequence starting with `BEGIN` state and ending +with one of `END`/`FAIL`/`CANCEL` states), calling appropriate callbacks associated with given gesture handler. + +### Arguments + +#### `gestureOrHandler` + +Represents either: + +1. Gesture handler component found by Jest queries (e.g. `getByTestId`) +2. Gesture found by [`getByGestureTestId()`](/docs/guides/testing#getbygesturetestidtestid) + +#### `eventList` + +Event data passed to appropriate callback. RNGH fills event list if required +data is missing using these rules: + +1. `oldState` is filled using state of the previous event. `BEGIN` events use + `UNDETERMINED` value as previous event. +2. Events after first `ACTIVE` state can omit `state` field. +3. Handler specific data is filled (e.g. `numberOfTouches`, `x` fields) with + defaults. +4. Missing `BEGIN` and `END` events are added with data copied from first and last + passed event, respectively. +5. If first event don't have `state` field, the `ACTIVE` state is assumed. + +Some examples: + +```jsx +const oldStateFilled = [ + { state: State.BEGAN }, + { state: State.ACTIVE }, + { state: State.END }, +]; // three events with specified state are fired. + +const implicitActiveState = [ + { state: State.BEGAN }, + { state: State.ACTIVE }, + { x: 5 }, + { state: State.END }, +]; // 4 events, including two ACTIVE events (second one has overridden additional data). + +const implicitBegin = [ + { x: 1, y: 11 }, + { x: 2, y: 12, state: State.FAILED }, +]; // 3 events, including implicit BEGAN, one ACTIVE, and one FAILED event with additional data. + +const implicitBeginAndEnd = [ + { x: 5, y: 15 }, + { x: 6, y: 16 }, + { x: 7, y: 17 }, +]; // 5 events, including 3 ACTIVE events and implicit BEGAN and END events. BEGAN uses first event's additional data, END uses last event's additional data. + +const allImplicits = []; // 3 events, one BEGIN, one ACTIVE, one END with defaults. +``` + +### Example + +Extracted from RNGH tests, check `Events.test.tsx` for full implementation. + +```tsx +it('sends events with additional data to handlers', () => { + const panHandlers = mockedEventHandlers(); + render(); + fireGestureHandler(getByGestureTestId('pan'), [ + { state: State.BEGAN, translationX: 0 }, + { state: State.ACTIVE, translationX: 10 }, + { translationX: 20 }, + { translationX: 20 }, + { state: State.END, translationX: 30 }, + ]); + + expect(panHandlers.active).toHaveBeenCalledTimes(3); + expect(panHandlers.active).toHaveBeenLastCalledWith( + expect.objectContaining({ translationX: 20 }) + ); +}); +``` + +## getByGestureTestId(testID) + +Returns opaque data type associated with gesture. Gesture is found via `testID` attribute in rendered +components (see [`withTestID` method](/docs/gestures/pan-gesture#withrefref)). + +### Arguments + +#### `testID` + +String identifying gesture. + +### Notes + +`testID` must be unique among components rendered in test. + +### Example + +See above example for `fireGestureHandler`. diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/troubleshooting.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/troubleshooting.md new file mode 100644 index 0000000000..0b78fd7926 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/troubleshooting.md @@ -0,0 +1,130 @@ +--- +id: troubleshooting +title: Troubleshooting +sidebar_position: 3 +--- + +## Troubleshooting + +Thanks for giving this library a try! We are sorry that you might have encountered issues though. Here is how you can seek help: + +1. Search over the [issues on Github](https://github.com/software-mansion/react-native-gesture-handler/issues). There is a chance someone had this problem in the past and it has been resolved! +2. When sure your problem hasn't been reported or was reported but the proposed solution doesn't work for you please follow [our issue reporting guidelines](#reporting-issues). +3. You can try seeking help on [Expo Developers Discord](https://chat.expo.dev/) where we often hang out. +4. If you feel like reading the source code I highly recommend it, as this is by far the best resource and gives you the most up to date insights into how the library works and what might be causing the bug. +5. If you managed to find the solution consider [contributing](/docs/#contributing) a fix or update our documentation to make this information easier to find for the others in the future. + +## Reporting issues + +This library is maintained by a very small team. +Please be mindful of that when reporting issue and when it happens that we can't get back to you as soon as you might expect. +We would love to fix all the problems as soon as possible, but often our time is constraint with other issues/features or projects. +To make it easier for us to understand your issue and to be able to approach it sooner you can help by: + +- Making sure the issue description is complete. Please include all the details about your environment (library version, RN version, device OS etc). +- It is the best to provide an example app that reproduces the issue you are having. Put it up on [gist](https://gist.github.com/), [snack](https://snack.expo.io) or create a repo on Github – it doesn't matter as long as we can easily pull it in, run and see the issue. +- Explain how you run your repro app and what steps to take to reproduce the issue. +- Isolate your issue from other dependencies you might be using and make the repro app as minimal as possible. +- If you have spent some time figuring out the root cause of the problem you can leave a note about your findings so far. +- **Do not comment on closed issues**. It is very unlikely that we are going to notice your comment in such a case. If the issue has been closed, but the proposed solution doesn't work for you, please open a new one providing all the information necessary and linking to the solution you have tried. + +## It's not a bug, it's a feature + +- 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` 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 to work, all composed gestures must be attached to the same `GestureHandlerRootView`. + +### Multiple instances of Gesture Handler were detected + +This error usually happens when in your project there exists more than one instance of Gesture Handler. It can occur when some of your dependencies have installed Gesture Handler inside their own `node_modules` instead of using it as a peer dependency. In this case two different versions of Gesture Handler JS module try to install the same Native Module. You can resolve this problem manually by modifying your `package.json` file. + +You can check which libraries are using Gesture Handler, for example, with the command: + +```bash +npm ls react-native-gesture-handler +yarn why react-native-gesture-handler +``` + +If you use `yarn` you should add [`resolution` property](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/). + +```json +"resolutions": { + "react-native-gesture-handler": +} +``` + +If you use `npm` you should add [`overrides` property](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides). + +```json +"overrides": { + "react-native-gesture-handler": +} +``` + +After that you need to run your package manager again + +```bash +yarn +``` + +or + +```bash +npm install +``` + +### Automatic [workletization](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary/#to-workletize) of gesture callbacks + +[Reanimated's Babel plugin](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary/#reanimated-babel-plugin) is setup in a way that automatically marks callbacks passed to gestures in the configuration chain as worklets. This means that as long as all your callbacks are defined in a single chain, you don't need to add a `'worklet';` directive at the beginning of the functions. Here is an example that will be automatically workletized: + +```jsx +const gesture = Gesture.Tap().onBegin(() => { + console.log(_WORKLET); +}); +``` + +And here are some examples that won't: + +```jsx +const gesture = Gesture.Tap(); +gesture.onBegin(() => { + console.log(_WORKLET); +}); +``` + +```jsx +const callback = () => { + console.log(_WORKLET); +}; +const gesture = Gesture.Tap().onBegin(callback); +``` + +```jsx +const callback = () => { + console.log(_WORKLET); +}; +const gesture = Gesture.Tap(); +gesture.onBegin(callback); +``` + +In the above cases, you should add a [`"worklet";`](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary/#worklet) directive at the beginning of the callbacks, like so: + +```jsx +const callback = () => { + // highlight-next-line + "worklet"; + console.log(_WORKLET); +}; +const gesture = Gesture.Tap().onBegin(callback); +``` + +```jsx +const callback = () => { + // highlight-next-line + "worklet"; + console.log(_WORKLET); +}; +const gesture = Gesture.Tap(); +gesture.onBegin(callback); +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/upgrading-to-2.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/upgrading-to-2.md new file mode 100644 index 0000000000..7ba133446b --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/guides/upgrading-to-2.md @@ -0,0 +1,117 @@ +--- +id: upgrading-to-2 +title: Upgrading to the new API introduced in Gesture Handler 2 +--- + +## Make sure to migrate off the `RNGestureHandlerEnabledRootView` (Android only) + +Gesture Handler 1 required you to override `createRootView` to return an instance of `RNGestureHandlerEnabledRootView`. This class has been the cause of many hard to debug and fix crashed and was deprecated in version 2.0, and subsequently removed in version 2.4. If you are still using it, check out [migrating off RNGHEnabledRootView guide](/docs/guides/migrating-off-rnghenabledroot). + +## Upgrading to the new API + +The most important change brought by the Gesture Handler 2 is the new Gesture API, along with the `GestureDetector` component. It makes declaring gesture easier, as it handles much of the work under the hood and reduces the amount of necessary boilerplate code. Instead of a separate component for every type of gesture, the `GestureDetector` component is used to attach gestures to the underlying view based on the configuration object passed to it. The configuration objects are created using the `Gesture` object, here is a simple example: + +```jsx +const tapGesture = Gesture.Tap().onStart(() => { + console.log('Tap!'); +}); +... +return ( + + + +); +``` + +As you can see, there are no `onGestureEvent` and `onHandlerStateChange` callbacks, instead the state machine is handled under the hood and relevant callbacks are called for specific transitions or events: + +- `onBegin` - called when the gesture transitions to the `BEGAN` state, which in most cases is when the gesture starts processing the touch stream - when the finger first touches the view +- `onStart` - called when the activation criteria for the gesture are met and it transitions from `BEGAN` to `ACTIVE` state +- `onUpdate` - replaces `onGestureEvent`, called every time the gesture sends a new event while it's in the `ACTIVE` state +- `onChange` - if defined, called just after `onUpdate`, the events passed to it are the same as the ones passed to `onUpdate` but they also contain `change` values which hold the change in value they represent since the last event (i.e. in case of the `Pan` gesture, the event will also contain `changeX` and `changeY` properties) +- `onEnd` - called when the gesture transitions from the `ACTIVE` state to either of `END`, `FAILED` or `CANCELLED` - you can tell whether the gesture finished due to user interaction or because of other reason (like getting cancelled by the system, or failure criteria) using the second value passed to the `onEnd` callback alongside the event +- `onFinalize` called when the gesture transitions into either of `END`, `FAILED` or `CANCELLED` state, if the gesture was `ACTIVE`, `onEnd` will be called first (similarly to `onEnd` you can determine the reason for finishing using the second argument) + +The difference between `onEnd` and `onFinalize` is that the `onEnd` will be called only if the gesture was `ACTIVE`, while `onFinalize` will be called if the gesture has `BEGAN`. This means that you can use `onEnd` to clean up after `onStart`, and `onFinalize` to clean up after `onBegin` (or both `onBegin` and `onStart`). + +### Configuring the gestures + +The new gesture objects are configured in the builder-like pattern. Instead of properties, each gesture provides methods that allow for its customization. In most cases the names of the methods are the same as the relevant props, or at least very similar. For example: + +```jsx +return ( + { + if (nativeEvent.state === State.ACTIVE) { + console.log('Tap!'); + } + }}> + + +); +``` + +Would have the same effect as: + +```jsx +const tapGesture = Gesture.Tap() + .numberOfTaps(2) + .maxDuration(500) + .maxDelay(500) + .maxDistance(10) + .onStart(() => { + console.log('Tap!'); + }); + +return ( + + + +); +``` + +You can check the modifiers available to specific gestures in the API Reference under Gestures. + +### Using multiple gestures on the same view + +Using the gesture handler components, if you wanted to have multiple gestures on one view, you would have to stack them on top of each other and, in case you wanted to use animations, add an `Animated.View` after each handler, resulting in a deep component tree, for example: + +```jsx +return ( + + + + + + + + + + + +); +``` + +With the `GestureDetector` you can use the [Gesture Composition API](/docs/fundamentals/gesture-composition) to stack the gestures onto one view: + +```jsx +const tapGesture = Gesture.Tap(); +const panGesture = Gesture.Pan(); +const pinchGesture = Gesture.Pinch(); + +return ( + + + +); +``` + +Similarly, you can use [`Gesture.Simultaneous`](/docs/fundamentals/gesture-composition#simultaneous) to replace stacked gesture handlers that should be able to recognize gestures simultaneously, and [`Gesture.Exclusive`](/docs/fundamentals/gesture-composition#exclusive) to replace stacked gesture handlers that require failure of others. + +### Replacing `waitFor` and `simultaneousHandlers` + +If you want to make relations between the gestures attached to the same view, you should use the [Gesture Composition API](/docs/fundamentals/gesture-composition) described above. However, if you want to make a relation between gestures attached to different views, or between gesture and an old gesture handler, you should use `simultaneousWithExternalGesture` instead of `simultaneousHandlers`, and `requireExternalGestureToFail` instead of `waitFor`. In case you need a ref object to pass to an old gesture handler, you can set it to the gesture using `.withRef(refObject)` modifier. diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/under-the-hood/_category_.json b/packages/docs-gesture-handler/versioned_docs/version-2.x/under-the-hood/_category_.json new file mode 100644 index 0000000000..849e82bec4 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/under-the-hood/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Under the hood", + "position": 5, + "link": { + "type": "generated-index" + } +} diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/under-the-hood/how-does-it-work.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/under-the-hood/how-does-it-work.md new file mode 100644 index 0000000000..4d613d4879 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/under-the-hood/how-does-it-work.md @@ -0,0 +1,22 @@ +--- +id: how-does-it-work +title: How does it work? +sidebar_label: How does it work? +--- + +### Units + +All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". +These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://reactnative.dev/docs/flexbox.html)). +They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. + +## iOS + +All gestures are implemented using [UIGestureRecognizers](https://developer.apple.com/documentation/uikit/uigesturerecognizer?language=objc), some of them have been slightly modified to allow for more customization and to conform to the state flow of RNGH. When you assign a gesture configuration to the `GestureDetector`, it creates all the required recognizers and assigns them to the child view of the detector. From this point most of the heavy lifting is handled by the [UIKit](https://developer.apple.com/documentation/uikit?language=objc) (with our help to correctly implement interactions between gestures). + +## 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 when you assign a gesture configuration to the `GestureDetector`, it initializes 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 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, it fails or gets cancelled) the orchestrator check 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...). diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/under-the-hood/state.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/under-the-hood/state.md new file mode 100644 index 0000000000..2cd6b0a5b2 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/under-the-hood/state.md @@ -0,0 +1,91 @@ +--- +id: state +title: Handler State +sidebar_label: Handler State +--- + +As described in ["About Gesture Handlers"](/docs/gesture-handlers/about-handlers), gesture handlers can be treated as ["state machines"](https://en.wikipedia.org/wiki/Finite-state_machine). +At any given time, each handler instance has an assigned state that can change when new touch events occur or can be forced to change by the touch system in certain circumstances. + +A gesture handler can be in one of the six possible states: + +- [Accessing state](#accessing-state) +- [State flows](#state-flows) +- [States](#states) + - [UNDETERMINED](#undetermined) + - [FAILED](#failed) + - [BEGAN](#began) + - [CANCELLED](#cancelled) + - [ACTIVE](#active) + - [END](#end) + +Each state has its own description below. + +## Accessing state + +We can monitor a handler's state changes by using the [`onHandlerStateChange`](/docs/gesture-handlers/common-gh#onhandlerstatechange) callback and the destructured `nativeEvent` argument passed to it. +This can be done by comparing the `nativeEvent`'s [`state`](/docs/gesture-handlers/common-gh#state) attribute to one of the constants exported under the `State` object (see example below). + +```jsx +import { State, LongPressGestureHandler } from 'react-native-gesture-handler'; + +class Demo extends Component { + _handleStateChange = ({ nativeEvent }) => { + if (nativeEvent.state === State.ACTIVE) { + Alert.alert('Longpress'); + } + }; + render() { + return ( + + Longpress me + + ); + } +} +``` + +## State flows + +The most typical flow of state is when a gesture handler picks up on an initial touch event then recognizes it then acknowledges its ending then resets itself back to the initial state. + +The flow looks as follows (longer arrows represent that there are possibly more touch events received before the state changes): + +[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`END`](#end) -> [`UNDETERMINED`](#undetermined) + +Another possible flow is when a handler receives touches that cause a recognition failure: + +[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`FAILED`](#failed) -> [`UNDETERMINED`](#undetermined) + +At last, when a handler does properly recognize the gesture but then is interrupted by the touch system. In that case, the gesture recognition is canceled and the flow looks as follows: + +[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`CANCELLED`](#cancelled) -> [`UNDETERMINED`](#undetermined) + +## States + +The section below describes all possible handler states: + +### UNDETERMINED + +This is the initial state of each handler and it goes into this state after it's done recognizing a gesture. + +### FAILED + +A handler received some touches but for some reason didn't recognize them. For example, if a finger travels more distance than a defined `maxDist` property allows, then the handler won't become active but will fail instead. Afterwards, it's state will be reset to `UNDETERMINED`. + +### BEGAN + +Handler has started receiving touch stream but hasn't yet received enough data to either [fail](#failed) or [activate](#active). + +### CANCELLED + +The gesture recognizer has received a signal (possibly new touches or a command from the touch system controller) resulting in the cancellation of a continuous gesture. The gesture's state will become `CANCELLED` until it is finally reset to the initial state, `UNDETERMINED`. + +### ACTIVE + +Handler has recognized a gesture. It will become and stay in the `ACTIVE` state until the gesture finishes (e.g. when user lifts the finger) or gets cancelled by the touch system. Under normal circumstances the state will then turn into `END`. In the case that a gesture is cancelled by the touch system, its state would then become `CANCELLED`. +Learn about [discrete and continuous handlers here](/docs/gesture-handlers/about-handlers#discrete-vs-continuous) to understand how long a handler can be kept in the `ACTIVE` state. + +### END + +The gesture recognizer has received touches signalling the end of a gesture. Its state will become `END` until it is reset to `UNDETERMINED`. diff --git a/packages/docs-gesture-handler/versioned_sidebars/version-2.x-sidebars.json b/packages/docs-gesture-handler/versioned_sidebars/version-2.x-sidebars.json new file mode 100644 index 0000000000..caea0c03ba --- /dev/null +++ b/packages/docs-gesture-handler/versioned_sidebars/version-2.x-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/packages/docs-gesture-handler/versions.json b/packages/docs-gesture-handler/versions.json index c339c0726b..fd4e814ac5 100644 --- a/packages/docs-gesture-handler/versions.json +++ b/packages/docs-gesture-handler/versions.json @@ -1 +1,4 @@ -["1.x"] +[ + "2.x", + "1.x" +] From cf3f81019e46237cf96043b51e46c4b29c4316ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Tue, 16 Dec 2025 15:38:38 +0100 Subject: [PATCH 17/45] Fix hover --- .../docs-gesture-handler/docs/gestures/use-hover-gesture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs-gesture-handler/docs/gestures/use-hover-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-hover-gesture.mdx index 664c92a78f..d76e67dd85 100644 --- a/packages/docs-gesture-handler/docs/gestures/use-hover-gesture.mdx +++ b/packages/docs-gesture-handler/docs/gestures/use-hover-gesture.mdx @@ -106,7 +106,7 @@ Visual effect applied to the view while the view is hovered. Defaults to `HoverE ## Callbacks - + ## Event data From 944d68934005969530fc27cae20baa05afc58f27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82?= Date: Tue, 16 Dec 2025 16:03:26 +0100 Subject: [PATCH 18/45] Fix old links --- .../api/gesture-handlers/common-gh.md | 20 ++++++------ .../api/gesture-handlers/force-gh.md | 6 ++-- .../api/gesture-handlers/longpress-gh.md | 4 +-- .../api/gesture-handlers/pan-gh.md | 10 +++--- .../api/gesture-handlers/pinch-gh.md | 2 +- .../api/gesture-handlers/tap-gh.md | 12 +++---- .../version-2.x/components/buttons.mdx | 12 +++---- .../version-2.x/fundamentals/installation.md | 2 +- .../gesture-handlers/about-handlers.md | 32 +++++++++---------- .../version-2.x/gesture-handlers/common-gh.md | 26 +++++++-------- .../gesture-handlers/create-native-wrapper.md | 4 +-- .../version-2.x/gesture-handlers/fling-gh.md | 10 +++--- .../version-2.x/gesture-handlers/force-gh.md | 12 +++---- .../gesture-handlers/interactions.md | 16 +++++----- .../gesture-handlers/longpress-gh.md | 10 +++--- .../gesture-handlers/nativeview-gh.md | 6 ++-- .../version-2.x/gesture-handlers/pan-gh.md | 28 ++++++++-------- .../version-2.x/gesture-handlers/pinch-gh.md | 8 ++--- .../gesture-handlers/rotation-gh.md | 8 ++--- .../version-2.x/gesture-handlers/tap-gh.md | 18 +++++------ .../_shared/base-continuous-gesture-config.md | 2 +- .../gestures/_shared/base-gesture-config.md | 16 +++++----- .../_shared/base-gesture-event-data.md | 2 +- .../version-2.x/gestures/composed-gestures.md | 2 +- .../version-2.x/gestures/fling-gesture.md | 4 +-- .../gestures/force-touch-gesture.md | 6 ++-- .../version-2.x/gestures/gesture-detector.md | 6 ++-- .../version-2.x/gestures/gesture.md | 20 ++++++------ .../version-2.x/gestures/hover-gesture.md | 7 ++-- .../gestures/long-press-gesture.md | 14 ++++---- .../version-2.x/gestures/manual-gesture.md | 2 +- .../version-2.x/gestures/native-gesture.md | 8 ++--- .../version-2.x/gestures/pan-gesture.md | 16 +++++----- .../version-2.x/gestures/pinch-gesture.md | 2 +- .../version-2.x/gestures/rotation-gesture.md | 2 +- .../version-2.x/gestures/state-manager.md | 10 +++--- .../version-2.x/gestures/tap-gesture.md | 20 ++++++------ .../version-2.x/gestures/touch-events.md | 4 +-- .../version-2.x/guides/quickstart/index.md | 2 +- .../version-2.x/guides/testing.md | 8 ++--- .../version-2.x/guides/troubleshooting.md | 6 ++-- .../version-2.x/guides/upgrading-to-2.md | 8 ++--- .../version-2.x/under-the-hood/state.md | 8 ++--- 43 files changed, 211 insertions(+), 210 deletions(-) diff --git a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/common-gh.md b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/common-gh.md index 4c077a212a..74eb5b52d1 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/common-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/common-gh.md @@ -20,28 +20,28 @@ This section describes properties that can be used with all gesture handler comp Accepts a boolean value. Indicates whether the given handler should be analyzing stream of touch events or not. -When set to `false` we can be sure that the handler's state will **never** become [`ACTIVE`](/docs/under-the-hood/state#active). -If the value gets updated while the handler already started recognizing a gesture, then the handler's state it will immediately change to [`FAILED`](/docs/under-the-hood/state#failed) or [`CANCELLED`](/docs/under-the-hood/state#cancelled) (depending on its current state). +When set to `false` we can be sure that the handler's state will **never** become [`ACTIVE`](/docs/1.x/state#active). +If the value gets updated while the handler already started recognizing a gesture, then the handler's state it will immediately change to [`FAILED`](/docs/1.x/state#failed) or [`CANCELLED`](/docs/1.x/state#cancelled) (depending on its current state). Default value is `true`. ### `shouldCancelWhenOutside` Accepts a boolean value. -When `true` the handler will [cancel](/docs/under-the-hood/state#cancelled) or [fail](/docs/under-the-hood/state#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. +When `true` the handler will [cancel](/docs/1.x/state#cancelled) or [fail](/docs/1.x/state#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. Default value of this property is different depending on the handler type. Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGestureHandler`](longpress-gh) and [`TapGestureHandler`](tap-gh) which default to `true`. ### `simultaneousHandlers` -Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set, the handler will be allowed to [activate](/docs/under-the-hood/state#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](/docs/under-the-hood/state#active) state. It will also prevent the provided handlers from [cancelling](/docs/under-the-hood/state#cancelled) the current handler when they [activate](/docs/under-the-hood/state#active). Read more in the [cross handler interaction](interactions.md#simultaneous-recognition) section. +Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set, the handler will be allowed to [activate](/docs/1.x/state#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](/docs/1.x/state#active) state. It will also prevent the provided handlers from [cancelling](/docs/1.x/state#cancelled) the current handler when they [activate](/docs/1.x/state#active). Read more in the [cross handler interaction](interactions.md#simultaneous-recognition) section. ### `waitFor` -Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set the handler will not [activate](/docs/under-the-hood/state#active) as long as the handlers provided by their refs are in the [`BEGAN`](/docs/under-the-hood/state#began) state. Read more in the [cross handler interaction](interactions.md#awaiting-other-handlers) section. +Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set the handler will not [activate](/docs/1.x/state#active) as long as the handlers provided by their refs are in the [`BEGAN`](/docs/1.x/state#began) state. Read more in the [cross handler interaction](interactions.md#awaiting-other-handlers) section. ### `hitSlop` -This parameter enables control over what part of the connected view area can be used to [begin](/docs/under-the-hood/state#began) recognizing the gesture. +This parameter enables control over what part of the connected view area can be used to [begin](/docs/1.x/state#began) recognizing the gesture. When a negative number is provided the bounds of the view will reduce the area by the given number of points in each of the sides evenly. Instead you can pass an object to specify how each boundary side should be reduced by providing different number of points for `left`, `right`, `top` or `bottom` sides. @@ -55,17 +55,17 @@ Specifying `width` or `height` is useful if we only want the gesture to activate ### `onGestureEvent` -Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](/docs/under-the-hood/state#active) state. Event payload depends on the particular handler type. Common set of event data attributes is documented [below](#event-data) and handler specific attributes are documented on the corresponding handler pages. E.g. event payload for [`PinchGestureHandler`](rotation-gh#event-data) contains `scale` attribute that represents how the distance between fingers changed since when the gesture started. +Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](/docs/1.x/state#active) state. Event payload depends on the particular handler type. Common set of event data attributes is documented [below](#event-data) and handler specific attributes are documented on the corresponding handler pages. E.g. event payload for [`PinchGestureHandler`](rotation-gh#event-data) contains `scale` attribute that represents how the distance between fingers changed since when the gesture started. Instead of a callback [`Animated.event`](https://reactnative.dev/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. ### `onHandlerStateChange` -Takes a callback that is going to be triggered when [state](/docs/under-the-hood/state) of the given handler changes. +Takes a callback that is going to be triggered when [state](/docs/1.x/state) of the given handler changes. The event payload contains the same payload as in case of [`onGestureEvent`](#ongestureevent) including handler specific event attributes some handlers may provide. -In addition `onHandlerStateChange` event payload contains `oldState` attribute which represents the [state](/docs/under-the-hood/state) of the handler right before the change. +In addition `onHandlerStateChange` event payload contains `oldState` attribute which represents the [state](/docs/1.x/state) of the handler right before the change. Instead of a callback [`Animated.event`](https://reactnative.dev/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. @@ -75,7 +75,7 @@ This section describes the attributes of event object being provided to [`onGest ### `state` -Current [state](/docs/under-the-hood/state) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](/docs/under-the-hood/state) to learn more about how to use it. +Current [state](/docs/1.x/state) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](/docs/1.x/state) to learn more about how to use it. ### `numberOfPointers` diff --git a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/force-gh.md b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/force-gh.md index d910ecb35f..d83a38f9b2 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/force-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/force-gh.md @@ -5,7 +5,7 @@ sidebar_label: Force touch --- A continuous gesture handler that recognizes force of a touch. It allows for tracking pressure of touch on some iOS devices. -The handler [activates](/docs/under-the-hood/state#active) when pressure of touch if greater or equal than `minForce`. It fails if pressure is greater than `maxForce` +The handler [activates](/docs/1.x/state#active) when pressure of touch if greater or equal than `minForce`. It fails if pressure is greater than `maxForce` Gesture callback can be used for continuous tracking of the touch pressure. It provides information for one finger (the first one). At the beginning of the gesture, the pressure factor is 0.0. As the pressure increases, the pressure factor increases proportionally. The maximum pressure is 1.0. @@ -19,11 +19,11 @@ See [set of properties inherited from base handler class](common-gh#properties). ### `minForce` -A minimal pressure that is required before handler can [activate](/docs/under-the-hood/state#active). Should be a value from range `[0.0, 1.0]`. Default is `0.2`. +A minimal pressure that is required before handler can [activate](/docs/1.x/state#active). Should be a value from range `[0.0, 1.0]`. Default is `0.2`. ### `maxForce` -A maximal pressure that could be applied for handler. If the pressure is greater, handler [fails](/docs/under-the-hood/state#failed). Should be a value from range `[0.0, 1.0]`. +A maximal pressure that could be applied for handler. If the pressure is greater, handler [fails](/docs/1.x/state#failed). Should be a value from range `[0.0, 1.0]`. ### `feedbackOnActivation` diff --git a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/longpress-gh.md b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/longpress-gh.md index 69db5218c3..fa53e37298 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/longpress-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/longpress-gh.md @@ -5,7 +5,7 @@ sidebar_label: Long press --- A discrete gesture handler that activates when the corresponding view is pressed for a sufficiently long time. -This handler's state will turn into [END](/docs/under-the-hood/state#end) immediately after the finger is released. +This handler's state will turn into [END](/docs/1.x/state#end) immediately after the finger is released. The handler will fail to recognize a touch event if the finger is lifted before the [minimum required time](#mindurationms) or if the finger is moved further than the [allowable distance](#maxdist). The handler is implemented using [UILongPressGestureRecognizer](https://developer.apple.com/documentation/uikit/uilongpressgesturerecognizer) on iOS and [LongPressGestureHandler](https://github.com/software-mansion/react-native-gesture-handler/blob/main/android/lib/src/main/java/com/swmansion/gesturehandler/LongPressGestureHandler.kt) on Android. @@ -20,7 +20,7 @@ Minimum time, expressed in milliseconds, that a finger must remain pressed on th ### `maxDist` -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. The default value is 10. +Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the handler hasn't yet [activated](/docs/1.x/state#active), it will fail to recognize the gesture. The default value is 10. ## Event data diff --git a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pan-gh.md b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pan-gh.md index 8f3490e3e1..3cb640b7bd 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pan-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pan-gh.md @@ -6,7 +6,7 @@ sidebar_label: Pan A continuous gesture handler that can recognize a panning (dragging) gesture and track its movement. -The handler [activates](/docs/under-the-hood/state#active) when a finger is placed on the screen and moved some initial distance. +The handler [activates](/docs/1.x/state#active) when a finger is placed on the screen and moved some initial distance. Configurations such as a minimum initial distance, specific vertical or horizontal pan detection and [number of fingers](#minPointers) required for activation (allowing for multifinger swipes) may be specified. @@ -16,7 +16,7 @@ The handler is implemented using [UIPanGestureRecognizer](https://developer.appl ## Custom activation criteria -The `PanGestureHandler` component exposes a number of properties that can be used to customize the criteria under which a handler will [activate](/docs/under-the-hood/state#active) or [fail](/docs/under-the-hood/state#fail) when recognizing a gesture. +The `PanGestureHandler` component exposes a number of properties that can be used to customize the criteria under which a handler will [activate](/docs/1.x/state#active) or [fail](/docs/1.x/state#fail) when recognizing a gesture. When more than one of such a property is set, `PanGestureHandler` expects all criteria to be met for successful recognition and at most one of the criteria to be overstepped to fail recognition. For example when both [`minDeltaX`](#mindeltax) and [`minDeltaY`](#mindeltay) are set to 20 we expect the finger to travel by 20 points in both the X and Y axis before the handler activates. @@ -45,15 +45,15 @@ See [set of properties inherited from base handler class](common-gh#properties). ### `minDist` -Minimum distance the finger (or multiple finger) need to travel before the handler [activates](/docs/under-the-hood/state#active). Expressed in points. +Minimum distance the finger (or multiple finger) need to travel before the handler [activates](/docs/1.x/state#active). Expressed in points. ### `minPointers` -A number of fingers that is required to be placed before handler can [activate](/docs/under-the-hood/state#active). Should be a higher or equal to 0 integer. +A number of fingers that is required to be placed before handler can [activate](/docs/1.x/state#active). Should be a higher or equal to 0 integer. ### `maxPointers` -When the given number of fingers is placed on the screen and handler hasn't yet [activated](/docs/under-the-hood/state#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. +When the given number of fingers is placed on the screen and handler hasn't yet [activated](/docs/1.x/state#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. ### `activeOffsetX` diff --git a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pinch-gh.md b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pinch-gh.md index 6e3c60b9dc..53c0de7063 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pinch-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pinch-gh.md @@ -5,7 +5,7 @@ sidebar_label: Pinch --- A continuous gesture handler that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. -The handler [activates](/docs/under-the-hood/state#active) when fingers are placed on the screen and change their position. +The handler [activates](/docs/1.x/state#active) when fingers are placed on the screen and change their position. Gesture callback can be used for continuous tracking of the pinch gesture. It provides information about velocity, anchor (focal) point of gesture and scale. The distance between the fingers is reported as a scale factor. At the beginning of the gesture, the scale factor is 1.0. As the distance between the two fingers increases, the scale factor increases proportionally. diff --git a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/tap-gh.md b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/tap-gh.md index 26f648111e..7fbfe6b04c 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/tap-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/tap-gh.md @@ -11,7 +11,7 @@ The fingers involved in these gestures must not move significantly from their in The required number of taps and allowed distance from initial position may be configured. For example, you might configure tap gesture recognizers to detect single taps, double taps, or triple taps. -In order for a handler to [activate](/docs/under-the-hood/state#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](/docs/under-the-hood/state#active), it will [END](/docs/under-the-hood/state#end). +In order for a handler to [activate](/docs/1.x/state#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](/docs/1.x/state#active), it will [END](/docs/1.x/state#end). ## Properties @@ -19,7 +19,7 @@ See [set of properties inherited from base handler class](common-gh#properties). ### `minPointers` -Minimum number of pointers (fingers) required to be placed before the handler [activates](/docs/under-the-hood/state#active). Should be a positive integer. The default value is 1. +Minimum number of pointers (fingers) required to be placed before the handler [activates](/docs/1.x/state#active). Should be a positive integer. The default value is 1. ### `maxDurationMs` @@ -31,19 +31,19 @@ Maximum time, expressed in milliseconds, that can pass before the next tap — i ### `numberOfTaps` -Number of tap gestures required to [activate](/docs/under-the-hood/state#active) the handler. The default value is 1. +Number of tap gestures required to [activate](/docs/1.x/state#active) the handler. The default value is 1. ### `maxDeltaX` -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture. If the finger travels further than the defined distance along the X axis and the handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. +Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture. If the finger travels further than the defined distance along the X axis and the handler hasn't yet [activated](/docs/1.x/state#active), it will fail to recognize the gesture. ### `maxDeltaY` -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture. If the finger travels further than the defined distance along the Y axis and the handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. +Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture. If the finger travels further than the defined distance along the Y axis and the handler hasn't yet [activated](/docs/1.x/state#active), it will fail to recognize the gesture. ### `maxDist` -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture. If the finger travels further than the defined distance and the handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. +Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture. If the finger travels further than the defined distance and the handler hasn't yet [activated](/docs/1.x/state#active), it will fail to recognize the gesture. ## Event data diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/buttons.mdx b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/buttons.mdx index e20bff3256..cde390a556 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/buttons.mdx +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/buttons.mdx @@ -15,11 +15,11 @@ Gesture handler library provides native components that can act as buttons. Thes Currently Gesture handler library exposes three components that render native touchable elements under the hood: -- [`BaseButton`](/docs/components/buttons/#basebutton) -- [`RectButton`](/docs/components/buttons/#rectbutton) -- [`BorderlessButton`](/docs/components/buttons/#borderlessbutton) +- [`BaseButton`](/docs/2.x/components/buttons/#basebutton) +- [`RectButton`](/docs/2.x/components/buttons/#rectbutton) +- [`BorderlessButton`](/docs/2.x/components/buttons/#borderlessbutton) -On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](/docs/gesture-handlers/common-gh/) and `NativeViewGestureHandler`'s [extra properties](/docs/gesture-handlers/nativeview-gh#properties) to be applied to them. +On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](/docs/2.x/gesture-handlers/common-gh/) and `NativeViewGestureHandler`'s [extra properties](/docs/2.x/gesture-handlers/nativeview-gh#properties) to be applied to them. **IMPORTANT**: In order to make buttons accessible, you have to wrap your children in a `View` with `accessible` and `accessibilityRole="button"` props. Example: @@ -75,7 +75,7 @@ defines the delay, in milliseconds, after which the `onLongPress` callback gets ## `RectButton` -This type of button component should be used when you deal with rectangular elements or blocks of content that can be pressed, for example table rows or buttons with text and icons. This component provides a platform specific interaction, rendering a rectangular ripple on Android or highlighting the background on iOS and on older versions of Android. In addition to the props of [`BaseButton`](/docs/components/buttons#basebutton), it accepts the following: +This type of button component should be used when you deal with rectangular elements or blocks of content that can be pressed, for example table rows or buttons with text and icons. This component provides a platform specific interaction, rendering a rectangular ripple on Android or highlighting the background on iOS and on older versions of Android. In addition to the props of [`BaseButton`](/docs/2.x/components/buttons#basebutton), it accepts the following: Below is a list of properties specific to `RectButton` component: @@ -89,7 +89,7 @@ opacity applied to the underlay when button is in active state. ## `BorderlessButton` -This type of button component should be used with simple icon-only or text-only buttons. The interaction will be different depending on platform: on Android a borderless ripple will be rendered (it means that the ripple will animate into a circle that can span outside of the view bounds), whereas on iOS the button will be dimmed (similar to how `TouchableOpacity` works). In addition to the props of [`BaseButton`](/docs/components/buttons#basebutton), it accepts the following: +This type of button component should be used with simple icon-only or text-only buttons. The interaction will be different depending on platform: on Android a borderless ripple will be rendered (it means that the ripple will animate into a circle that can span outside of the view bounds), whereas on iOS the button will be dimmed (similar to how `TouchableOpacity` works). In addition to the props of [`BaseButton`](/docs/2.x/components/buttons#basebutton), it accepts the following: Below is a list of properties specific to `BorderlessButton` component: diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/installation.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/installation.md index 1764de7cd0..43977e49e9 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/installation.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/installation.md @@ -24,7 +24,7 @@ import TabItem from '@theme/TabItem'; | 2.10.0+ | 0.64.0+ | | 2.0.0+ | 0.63.0+ | -In order to fully utilize the [touch events](/docs/gestures/touch-events/) you also need to use `react-native-reanimated` 2.3.0 or newer. +In order to fully utilize the [touch events](/docs/2.x/gestures/touch-events/) you also need to use `react-native-reanimated` 2.3.0 or newer. Setting up `react-native-gesture-handler` is pretty straightforward: diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/about-handlers.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/about-handlers.md index c67eb59173..6565c773a2 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/about-handlers.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/about-handlers.md @@ -6,7 +6,7 @@ sidebar_position: 1 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: Gesture handlers are the core building blocks of this library. @@ -16,10 +16,10 @@ Each handler type is capable of recognizing one type of gesture (pan, pinch, etc Handlers analyze touch stream synchronously in the UI thread. This allows for uninterrupted interactions even when the Javascript thread is blocked. -Each handler works as an isolated state machine. It takes touch stream as an input and based on it, it can flip between [states](/docs/under-the-hood/state). +Each handler works as an isolated state machine. It takes touch stream as an input and based on it, it can flip between [states](/docs/2.x/under-the-hood/state). When a gesture starts, based on the position where the finger was placed, a set of handlers that may be interested in recognizing the gesture is selected. All the touch events (touch down, move, up, or when other fingers are placed or lifted) are delivered to all of the handlers selected initially. -When one gesture becomes [active](/docs/under-the-hood/state#active), it cancels all the other gestures (read more about how to influence this process in ["Cross handler interactions"](/docs/gesture-handlers/interactions) section). +When one gesture becomes [active](/docs/2.x/under-the-hood/state#active), it cancels all the other gestures (read more about how to influence this process in ["Cross handler interactions"](/docs/2.x/gesture-handlers/interactions) section). Gesture handler components do not instantiate a native view in the view hierarchy. Instead, they are kept in library's own registry and are only connected to native views. When using any of the gesture handler components, it is important for it to have a native view rendered as a child. Since handler components don't have corresponding views in the hierarchy, the events registered with them are actually hooked into the underlying view. @@ -28,23 +28,23 @@ Since handler components don't have corresponding views in the hierarchy, the ev Currently, the library provides the following list of gestures. Their parameters and attributes they provide to gesture events are documented under each gesture page: -- [`PanGestureHandler`](/docs/gesture-handlers/pan-gh) -- [`TapGestureHandler`](/docs/gesture-handlers/tap-gh) -- [`LongPressGestureHandler`](/docs/gesture-handlers/longpress-gh) -- [`RotationGestureHandler`](/docs/gesture-handlers/rotation-gh) -- [`FlingGestureHandler`](/docs/gesture-handlers/fling-gh) -- [`PinchGestureHandler`](/docs/gesture-handlers/pinch-gh) -- [`ForceTouchGestureHandler`](/docs/gesture-handlers/force-gh) +- [`PanGestureHandler`](/docs/2.x/gesture-handlers/pan-gh) +- [`TapGestureHandler`](/docs/2.x/gesture-handlers/tap-gh) +- [`LongPressGestureHandler`](/docs/2.x/gesture-handlers/longpress-gh) +- [`RotationGestureHandler`](/docs/2.x/gesture-handlers/rotation-gh) +- [`FlingGestureHandler`](/docs/2.x/gesture-handlers/fling-gh) +- [`PinchGestureHandler`](/docs/2.x/gesture-handlers/pinch-gh) +- [`ForceTouchGestureHandler`](/docs/2.x/gesture-handlers/force-gh) ### Discrete vs continuous We distinguish between two types of gestures: discrete and continuous. -Continuous gesture handlers can be [active](/docs/under-the-hood/state#active) for a long period of time and will generate a stream of [gesture events](/docs/gesture-handlers/common-gh#ongestureevent) until the gesture is [over](/docs/under-the-hood/state#ended). -An example of a continuous handler is [`PanGestureHandler`](/docs/gesture-handlers/pan-gh) that once [activated](/docs/under-the-hood/state#active), will start providing updates about [translation](/docs/gesture-handlers/pan-gh#translationx) and other properties. +Continuous gesture handlers can be [active](/docs/2.x/under-the-hood/state#active) for a long period of time and will generate a stream of [gesture events](/docs/2.x/gesture-handlers/common-gh#ongestureevent) until the gesture is [over](/docs/2.x/under-the-hood/state#ended). +An example of a continuous handler is [`PanGestureHandler`](/docs/2.x/gesture-handlers/pan-gh) that once [activated](/docs/2.x/under-the-hood/state#active), will start providing updates about [translation](/docs/2.x/gesture-handlers/pan-gh#translationx) and other properties. -On the other hand, discrete gesture handlers once [activated](/docs/under-the-hood/state#active) will not stay in the active state but will [end](/docs/under-the-hood/state#ended) immediately. -[`LongPressGestureHandler`](/docs/gesture-handlers/longpress-gh) is a discrete handler, as it only detects if the finger is placed for a sufficiently long period of time, it does not track finger movements (as that's the responsibility of [`PanGestureHandler`](/docs/gesture-handlers/pan-gh)). +On the other hand, discrete gesture handlers once [activated](/docs/2.x/under-the-hood/state#active) will not stay in the active state but will [end](/docs/2.x/under-the-hood/state#ended) immediately. +[`LongPressGestureHandler`](/docs/2.x/gesture-handlers/longpress-gh) is a discrete handler, as it only detects if the finger is placed for a sufficiently long period of time, it does not track finger movements (as that's the responsibility of [`PanGestureHandler`](/docs/2.x/gesture-handlers/pan-gh)). Keep in mind that `onGestureEvent` is only generated in continuous gesture handlers and shouldn't be used in the `TapGestureHandler` and other discrete handlers. @@ -77,7 +77,7 @@ class Multitap extends Component { ### Using native components -Gesture handler library exposes a set of components normally available in React Native that are wrapped in [`NativeViewGestureHandler`](/docs/gesture-handlers/nativeview-gh). +Gesture handler library exposes a set of components normally available in React Native that are wrapped in [`NativeViewGestureHandler`](/docs/2.x/gesture-handlers/nativeview-gh). Here is a list of exposed components: - `ScrollView` @@ -86,7 +86,7 @@ Here is a list of exposed components: - `TextInput` - `DrawerLayoutAndroid` (**Android only**) -If you want to use other handlers or [buttons](/docs/components/buttons) nested in a `ScrollView`, use the [`waitFor`](/docs/gesture-handlers/common-gh#waitfor) property to define interaction between a handler and `ScrollView` +If you want to use other handlers or [buttons](/docs/2.x/components/buttons) nested in a `ScrollView`, use the [`waitFor`](/docs/2.x/gesture-handlers/common-gh#waitfor) property to define interaction between a handler and `ScrollView` ### Events with `useNativeDriver` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/common-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/common-gh.md index 58421e27ac..0133c4e096 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/common-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/common-gh.md @@ -6,7 +6,7 @@ sidebar_position: 4 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: This page covers the common set of properties all gesture handler components expose. @@ -25,34 +25,34 @@ This section describes properties that can be used with all gesture handler comp Accepts a boolean value. Indicates whether the given handler should be analyzing stream of touch events or not. -When set to `false` we can be sure that the handler's state will **never** become [`ACTIVE`](/docs/under-the-hood/state#active). -If the value gets updated while the handler already started recognizing a gesture, then the handler's state it will immediately change to [`FAILED`](/docs/under-the-hood/state#failed) or [`CANCELLED`](/docs/under-the-hood/state#cancelled) (depending on its current state). +When set to `false` we can be sure that the handler's state will **never** become [`ACTIVE`](/docs/2.x/under-the-hood/state#active). +If the value gets updated while the handler already started recognizing a gesture, then the handler's state it will immediately change to [`FAILED`](/docs/2.x/under-the-hood/state#failed) or [`CANCELLED`](/docs/2.x/under-the-hood/state#cancelled) (depending on its current state). Default value is `true`. ### `shouldCancelWhenOutside` Accepts a boolean value. -When `true` the handler will [cancel](/docs/under-the-hood/state#cancelled) or [fail](/docs/under-the-hood/state#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. +When `true` the handler will [cancel](/docs/2.x/under-the-hood/state#cancelled) or [fail](/docs/2.x/under-the-hood/state#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. Default value of this property is different depending on the handler type. -Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGestureHandler`](/docs/gesture-handlers/longpress-gh) and [`TapGestureHandler`](/docs/gesture-handlers/tap-gh) which default to `true`. +Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGestureHandler`](/docs/2.x/gesture-handlers/longpress-gh) and [`TapGestureHandler`](/docs/2.x/gesture-handlers/tap-gh) which default to `true`. ### `cancelsTouchesInView` (**iOS only**) Accepts a boolean value. -When `true`, the handler will cancel touches for native UI components (`UIButton`, `UISwitch`, etc) it's attached to when it becomes [`ACTIVE`](/docs/under-the-hood/state#active). +When `true`, the handler will cancel touches for native UI components (`UIButton`, `UISwitch`, etc) it's attached to when it becomes [`ACTIVE`](/docs/2.x/under-the-hood/state#active). Default value is `true`. ### `simultaneousHandlers` -Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set, the handler will be allowed to [activate](/docs/under-the-hood/state#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](/docs/under-the-hood/state#active) state. It will also prevent the provided handlers from [cancelling](/docs/under-the-hood/state#cancelled) the current handler when they [activate](/docs/under-the-hood/state#active). Read more in the [cross handler interaction](/docs/gesture-handlers/interactions#simultaneous-recognition) section. +Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set, the handler will be allowed to [activate](/docs/2.x/under-the-hood/state#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](/docs/2.x/under-the-hood/state#active) state. It will also prevent the provided handlers from [cancelling](/docs/2.x/under-the-hood/state#cancelled) the current handler when they [activate](/docs/2.x/under-the-hood/state#active). Read more in the [cross handler interaction](/docs/2.x/gesture-handlers/interactions#simultaneous-recognition) section. ### `waitFor` -Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set the handler will not [activate](/docs/under-the-hood/state#active) as long as the handlers provided by their refs are in the [`BEGAN`](/docs/under-the-hood/state#began) state. Read more in the [cross handler interaction](/docs/gesture-handlers/interactions#awaiting-other-handlers) section. +Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set the handler will not [activate](/docs/2.x/under-the-hood/state#active) as long as the handlers provided by their refs are in the [`BEGAN`](/docs/2.x/under-the-hood/state#began) state. Read more in the [cross handler interaction](/docs/2.x/gesture-handlers/interactions#awaiting-other-handlers) section. ### `hitSlop` -This parameter enables control over what part of the connected view area can be used to [begin](/docs/under-the-hood/state#began) recognizing the gesture. +This parameter enables control over what part of the connected view area can be used to [begin](/docs/2.x/under-the-hood/state#began) recognizing the gesture. When a negative number is provided the bounds of the view will reduce the area by the given number of points in each of the sides evenly. Instead you can pass an object to specify how each boundary side should be reduced by providing different number of points for `left`, `right`, `top` or `bottom` sides. @@ -74,17 +74,17 @@ This parameter allows to specify which cursor should be used when gesture activa ### `onGestureEvent` -Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](/docs/under-the-hood/state#active) state. Event payload depends on the particular handler type. Common set of event data attributes is documented [below](#event-data) and handler specific attributes are documented on the corresponding handler pages. E.g. event payload for [`PinchGestureHandler`](/docs/gesture-handlers/rotation-gh#event-data) contains `scale` attribute that represents how the distance between fingers changed since when the gesture started. +Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](/docs/2.x/under-the-hood/state#active) state. Event payload depends on the particular handler type. Common set of event data attributes is documented [below](#event-data) and handler specific attributes are documented on the corresponding handler pages. E.g. event payload for [`PinchGestureHandler`](/docs/2.x/gesture-handlers/rotation-gh#event-data) contains `scale` attribute that represents how the distance between fingers changed since when the gesture started. Instead of a callback [`Animated.event`](https://reactnative.dev/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. ### `onHandlerStateChange` -Takes a callback that is going to be triggered when [state](/docs/under-the-hood/state) of the given handler changes. +Takes a callback that is going to be triggered when [state](/docs/2.x/under-the-hood/state) of the given handler changes. The event payload contains the same payload as in case of [`onGestureEvent`](#ongestureevent) including handler specific event attributes some handlers may provide. -In addition `onHandlerStateChange` event payload contains `oldState` attribute which represents the [state](/docs/under-the-hood/state) of the handler right before the change. +In addition `onHandlerStateChange` event payload contains `oldState` attribute which represents the [state](/docs/2.x/under-the-hood/state) of the handler right before the change. Instead of a callback [`Animated.event`](https://reactnative.dev/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. @@ -94,7 +94,7 @@ This section describes the attributes of event object being provided to [`onGest ### `state` -Current [state](/docs/under-the-hood/state) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](/docs/under-the-hood/state) to learn more about how to use it. +Current [state](/docs/2.x/under-the-hood/state) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](/docs/2.x/under-the-hood/state) to learn more about how to use it. ### `numberOfPointers` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/create-native-wrapper.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/create-native-wrapper.md index aa84e63b37..1bd50a5485 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/create-native-wrapper.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/create-native-wrapper.md @@ -6,7 +6,7 @@ sidebar_position: 13 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: Creates provided component with NativeViewGestureHandler, allowing it to be part of RNGH's @@ -20,7 +20,7 @@ The component we want to wrap. ### config -Config is an object with properties that can be used on [`NativeViewGestureHandler`](/docs/gesture-handlers/nativeview-gh) +Config is an object with properties that can be used on [`NativeViewGestureHandler`](/docs/2.x/gesture-handlers/nativeview-gh) ## Returns diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/fling-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/fling-gh.md index baedfc15e1..171f43087d 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/fling-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/fling-gh.md @@ -6,18 +6,18 @@ sidebar_position: 9 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A discrete gesture handler that activates when the movement is sufficiently long and fast. -Handler gets [ACTIVE](/docs/under-the-hood/state#active) when movement is sufficiently long and it does not take too much time. -When handler gets activated it will turn into [END](/docs/under-the-hood/state#end) state when finger is released. +Handler gets [ACTIVE](/docs/2.x/under-the-hood/state#active) when movement is sufficiently long and it does not take too much time. +When handler gets activated it will turn into [END](/docs/2.x/under-the-hood/state#end) state when finger is released. The handler will fail to recognize if the finger is lifted before being activated. The handler is implemented using [UISwipeGestureRecognizer](https://developer.apple.com/documentation/uikit/uiswipegesturerecognizer) on iOS and from scratch on Android. ## Properties -See [set of properties inherited from base handler class](/docs/gesture-handlers/common-gh#properties). Below is a list of properties specific to `FlingGestureHandler` component: +See [set of properties inherited from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). Below is a list of properties specific to `FlingGestureHandler` component: ### `direction` @@ -39,7 +39,7 @@ Determine exact number of points required to handle the fling gesture. ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `FlingGestureHandler`: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `FlingGestureHandler`: ### `x` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/force-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/force-gh.md index 6e23205984..110ca1780d 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/force-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/force-gh.md @@ -6,11 +6,11 @@ sidebar_position: 11 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A continuous gesture handler that recognizes force of a touch. It allows for tracking pressure of touch on some iOS devices. -The handler [activates](/docs/under-the-hood/state#active) when pressure of touch if greater or equal than `minForce`. It fails if pressure is greater than `maxForce` +The handler [activates](/docs/2.x/under-the-hood/state#active) when pressure of touch if greater or equal than `minForce`. It fails if pressure is greater than `maxForce` Gesture callback can be used for continuous tracking of the touch pressure. It provides information for one finger (the first one). At the beginning of the gesture, the pressure factor is 0.0. As the pressure increases, the pressure factor increases proportionally. The maximum pressure is 1.0. @@ -20,15 +20,15 @@ Since this behaviour is only provided on some iOS devices, this handler should n # Properties -See [set of properties inherited from base handler class](/docs/gesture-handlers/common-gh#properties). Below is a list of properties specific to `ForceTouchGestureHandler` component: +See [set of properties inherited from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). Below is a list of properties specific to `ForceTouchGestureHandler` component: ### `minForce` -A minimal pressure that is required before handler can [activate](/docs/under-the-hood/state#active). Should be a value from range `[0.0, 1.0]`. Default is `0.2`. +A minimal pressure that is required before handler can [activate](/docs/2.x/under-the-hood/state#active). Should be a value from range `[0.0, 1.0]`. Default is `0.2`. ### `maxForce` -A maximal pressure that could be applied for handler. If the pressure is greater, handler [fails](/docs/under-the-hood/state#failed). Should be a value from range `[0.0, 1.0]`. +A maximal pressure that could be applied for handler. If the pressure is greater, handler [fails](/docs/2.x/under-the-hood/state#failed). Should be a value from range `[0.0, 1.0]`. ### `feedbackOnActivation` @@ -36,7 +36,7 @@ Boolean value defining if haptic feedback has to be performed on activation. ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `ForceTouchGestureHandler`: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `ForceTouchGestureHandler`: ### `force` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/interactions.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/interactions.md index 64b9636051..e225e0e2b0 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/interactions.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/interactions.md @@ -6,10 +6,10 @@ sidebar_position: 3 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: -Gesture handlers can "communicate" with each other to support complex gestures and control how they _[activate](/docs/under-the-hood/state#active)_ in certain scenarios. +Gesture handlers can "communicate" with each other to support complex gestures and control how they _[activate](/docs/2.x/under-the-hood/state#active)_ in certain scenarios. There are two means of achieving that described in the sections below. In each case, it is necessary to provide a reference of one handler as a property to the other. @@ -17,17 +17,17 @@ Gesture handler relies on ref objects created using [`React.createRef()`](https: ## Simultaneous recognition -By default, only one gesture handler is allowed to be in the [`ACTIVE`](/docs/under-the-hood/state#active) state. -So when a gesture handler recognizes a gesture it [cancels](/docs/under-the-hood/state#cancelled) all other handlers in the [`BEGAN`](/docs/under-the-hood/state#began) state and prevents any new handlers from receiving a stream of touch events as long as it remains [`ACTIVE`](/docs/under-the-hood/state#active). +By default, only one gesture handler is allowed to be in the [`ACTIVE`](/docs/2.x/under-the-hood/state#active) state. +So when a gesture handler recognizes a gesture it [cancels](/docs/2.x/under-the-hood/state#cancelled) all other handlers in the [`BEGAN`](/docs/2.x/under-the-hood/state#began) state and prevents any new handlers from receiving a stream of touch events as long as it remains [`ACTIVE`](/docs/2.x/under-the-hood/state#active). -This behavior can be altered using the [`simultaneousHandlers`](/docs/gesture-handlers/common-gh#simultaneoushandlers) property (available for all types of handlers). +This behavior can be altered using the [`simultaneousHandlers`](/docs/2.x/gesture-handlers/common-gh#simultaneoushandlers) property (available for all types of handlers). This property accepts a ref or an array of refs to other handlers. -Handlers connected in this way will be allowed to remain in the [`ACTIVE`](/docs/under-the-hood/state#active) state at the same time. +Handlers connected in this way will be allowed to remain in the [`ACTIVE`](/docs/2.x/under-the-hood/state#active) state at the same time. ### Use cases Simultaneous recognition needs to be used when implementing a photo preview component that supports zooming (scaling) the photo, rotating and panning it while zoomed in. -In this case we would use a [`PinchGestureHandler`](/docs/gesture-handlers/pinch-gh), [`RotationGestureHandler`](/docs/gesture-handlers/rotation-gh) and [`PanGestureHandler`](/docs/gesture-handlers/pan-gh) that would have to simultaneously recognize gestures. +In this case we would use a [`PinchGestureHandler`](/docs/2.x/gesture-handlers/pinch-gh), [`RotationGestureHandler`](/docs/2.x/gesture-handlers/rotation-gh) and [`PanGestureHandler`](/docs/2.x/gesture-handlers/pan-gh) that would have to simultaneously recognize gestures. ### Example @@ -75,7 +75,7 @@ class PinchableBox extends React.Component { A good example where awaiting is necessary is when we want to have single and double tap handlers registered for one view (a button). In such a case we need to make single tap handler await a double tap. -Otherwise if we try to perform a double tap the single tap handler will fire just after we hit the button for the first time, consequently [cancelling](/docs/under-the-hood/state#cancelled) the double tap handler. +Otherwise if we try to perform a double tap the single tap handler will fire just after we hit the button for the first time, consequently [cancelling](/docs/2.x/under-the-hood/state#cancelled) the double tap handler. ### Example diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/longpress-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/longpress-gh.md index 2b2e751b99..4d01bab2a5 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/longpress-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/longpress-gh.md @@ -6,18 +6,18 @@ sidebar_position: 7 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A discrete gesture handler that activates when the corresponding view is pressed for a sufficiently long time. -This handler's state will turn into [END](/docs/under-the-hood/state#end) immediately after the finger is released. +This handler's state will turn into [END](/docs/2.x/under-the-hood/state#end) immediately after the finger is released. The handler will fail to recognize a touch event if the finger is lifted before the [minimum required time](#mindurationms) or if the finger is moved further than the [allowable distance](#maxdist). The handler is implemented using [UILongPressGestureRecognizer](https://developer.apple.com/documentation/uikit/uilongpressgesturerecognizer) on iOS and [LongPressGestureHandler](https://github.com/software-mansion/react-native-gesture-handler/blob/main/android/src/main/java/com/swmansion/gesturehandler/core/LongPressGestureHandler.kt) on Android. ## Properties -See [set of properties inherited from base handler class](/docs/gesture-handlers/common-gh#properties). Below is a list of properties specific to the `LongPressGestureHandler` component: +See [set of properties inherited from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). Below is a list of properties specific to the `LongPressGestureHandler` component: ### `minDurationMs` @@ -25,11 +25,11 @@ Minimum time, expressed in milliseconds, that a finger must remain pressed on th ### `maxDist` -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. The default value is 10. +Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active), it will fail to recognize the gesture. The default value is 10. ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to the `LongPressGestureHandler` component: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to the `LongPressGestureHandler` component: ### `x` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/nativeview-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/nativeview-gh.md index 5c494c9bff..f8712a0d24 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/nativeview-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/nativeview-gh.md @@ -6,17 +6,17 @@ sidebar_position: 12 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A gesture handler that allows other touch handling components to participate in RNGH's gesture system. -Used by [`createNativeWrapper()`](/docs/gesture-handlers/create-native-wrapper). +Used by [`createNativeWrapper()`](/docs/2.x/gesture-handlers/create-native-wrapper). ## Properties -See [set of properties inherited from base handler class](/docs/gesture-handlers/common-gh#properties). Below is a list of properties specific to `NativeViewGestureHandler` component: +See [set of properties inherited from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). Below is a list of properties specific to `NativeViewGestureHandler` component: ### `shouldActivateOnStart` (**Android only**) diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pan-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pan-gh.md index d70c80cdd0..3cf8218652 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pan-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pan-gh.md @@ -6,12 +6,12 @@ sidebar_position: 5 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A continuous gesture handler that can recognize a panning (dragging) gesture and track its movement. -The handler [activates](/docs/under-the-hood/state#active) when a finger is placed on the screen and moved some initial distance. +The handler [activates](/docs/2.x/under-the-hood/state#active) when a finger is placed on the screen and moved some initial distance. Configurations such as a minimum initial distance, specific vertical or horizontal pan detection and [number of fingers](#minPointers) required for activation (allowing for multifinger swipes) may be specified. @@ -21,7 +21,7 @@ The handler is implemented using [UIPanGestureRecognizer](https://developer.appl ## Custom activation criteria -The `PanGestureHandler` component exposes a number of properties that can be used to customize the criteria under which a handler will [activate](/docs/under-the-hood/state#active) or [fail](/docs/under-the-hood/state#fail) when recognizing a gesture. +The `PanGestureHandler` component exposes a number of properties that can be used to customize the criteria under which a handler will [activate](/docs/2.x/under-the-hood/state#active) or [fail](/docs/2.x/under-the-hood/state#fail) when recognizing a gesture. When more than one of such a property is set, `PanGestureHandler` expects all criteria to be met for successful recognition and at most one of the criteria to be overstepped to fail recognition. For example when both [`minDeltaX`](#mindeltax) and [`minDeltaY`](#mindeltay) are set to 20 we expect the finger to travel by 20 points in both the X and Y axis before the handler activates. @@ -46,19 +46,19 @@ If you wish to track the "center of mass" virtual pointer and account for its ch ## Properties -See [set of properties inherited from base handler class](/docs/gesture-handlers/common-gh#properties). Below is a list of properties specific to `PanGestureHandler` component: +See [set of properties inherited from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). Below is a list of properties specific to `PanGestureHandler` component: ### `minDist` -Minimum distance the finger (or multiple finger) need to travel before the handler [activates](/docs/under-the-hood/state#active). Expressed in points. +Minimum distance the finger (or multiple finger) need to travel before the handler [activates](/docs/2.x/under-the-hood/state#active). Expressed in points. ### `minPointers` -A number of fingers that is required to be placed before handler can [activate](/docs/under-the-hood/state#active). Should be a higher or equal to 0 integer. +A number of fingers that is required to be placed before handler can [activate](/docs/2.x/under-the-hood/state#active). Should be a higher or equal to 0 integer. ### `maxPointers` -When the given number of fingers is placed on the screen and handler hasn't yet [activated](/docs/under-the-hood/state#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. +When the given number of fingers is placed on the screen and handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. ### `activeOffsetX` @@ -88,37 +88,37 @@ If only one number `p` is given a range of `(-inf, p)` will be used if `p` is hi > This method is deprecated but supported for backward compatibility. Instead of using `maxDeltaX={N}` you can do `failOffsetX={[-N, N]}`. -When the finger travels the given distance expressed in points along X axis and handler hasn't yet [activated](/docs/under-the-hood/state#active) it will fail recognizing the gesture. +When the finger travels the given distance expressed in points along X axis and handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active) it will fail recognizing the gesture. ### `maxDeltaY` > This method is deprecated but supported for backward compatibility. Instead of using `maxDeltaY={N}` you can do `failOffsetY={[-N, N]}`. -When the finger travels the given distance expressed in points along Y axis and handler hasn't yet [activated](/docs/under-the-hood/state#active) it will fail recognizing the gesture. +When the finger travels the given distance expressed in points along Y axis and handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active) it will fail recognizing the gesture. ### `minOffsetX` > This method is deprecated but supported for backward compatibility. Instead of using `minOffsetX={N}` you can do `activeOffsetX={N}`. -Minimum distance along X (in points) axis the finger (or multiple finger) need to travel before the handler [activates](/docs/under-the-hood/state#active). If set to a lower or equal to 0 value we expect the finger to travel "left" by the given distance. When set to a higher or equal to 0 number the handler will activate on a movement to the "right". If you wish for the movement direction to be ignored use [`minDeltaX`](#mindeltax) instead. +Minimum distance along X (in points) axis the finger (or multiple finger) need to travel before the handler [activates](/docs/2.x/under-the-hood/state#active). If set to a lower or equal to 0 value we expect the finger to travel "left" by the given distance. When set to a higher or equal to 0 number the handler will activate on a movement to the "right". If you wish for the movement direction to be ignored use [`minDeltaX`](#mindeltax) instead. ### `minOffsetY` > This method is deprecated but supported for backward compatibility. Instead of using `minOffsetY={N}` you can do `activeOffsetY={N}`. -Minimum distance along Y (in points) axis the finger (or multiple finger) need to travel before the handler [activates](/docs/under-the-hood/state#active). If set to a lower or equal to 0 value we expect the finger to travel "up" by the given distance. When set to a higher or equal to 0 number the handler will activate on a movement to the "bottom". If you wish for the movement direction to be ignored use [`minDeltaY`](#mindeltay) instead. +Minimum distance along Y (in points) axis the finger (or multiple finger) need to travel before the handler [activates](/docs/2.x/under-the-hood/state#active). If set to a lower or equal to 0 value we expect the finger to travel "up" by the given distance. When set to a higher or equal to 0 number the handler will activate on a movement to the "bottom". If you wish for the movement direction to be ignored use [`minDeltaY`](#mindeltay) instead. ### `minDeltaX` > This method is deprecated but supported for backward compatibility. Instead of using `minDeltaX={N}` you can do `activeOffsetX={[-N, N]}`. -Minimum distance along X (in points) axis the finger (or multiple finger) need to travel (left or right) before the handler [activates](/docs/under-the-hood/state#active). Unlike [`minoffsetx`](#minoffsetx) this parameter accepts only non-lower or equal to 0 numbers that represents the distance in point units. If you want for the handler to [activate](/docs/under-the-hood/state#active) for the movement in one particular direction use [`minOffsetX`](#minoffsetx) instead. +Minimum distance along X (in points) axis the finger (or multiple finger) need to travel (left or right) before the handler [activates](/docs/2.x/under-the-hood/state#active). Unlike [`minoffsetx`](#minoffsetx) this parameter accepts only non-lower or equal to 0 numbers that represents the distance in point units. If you want for the handler to [activate](/docs/2.x/under-the-hood/state#active) for the movement in one particular direction use [`minOffsetX`](#minoffsetx) instead. ### `minDeltaY` > This method is deprecated but supported for backward compatibility. Instead of using `minDeltaY={N}` you can do `activeOffsetY={[-N, N]}`. -Minimum distance along Y (in points) axis the finger (or multiple finger) need to travel (top or bottom) before the handler [activates](/docs/under-the-hood/state#active). Unlike [`minOffsetY`](#minoffsety) this parameter accepts only non-lower or equal to 0 numbers that represents the distance in point units. If you want for the handler to [activate](/docs/under-the-hood/state#active) for the movement in one particular direction use [`minOffsetY`](#minoffsety) instead. +Minimum distance along Y (in points) axis the finger (or multiple finger) need to travel (top or bottom) before the handler [activates](/docs/2.x/under-the-hood/state#active). Unlike [`minOffsetY`](#minoffsety) this parameter accepts only non-lower or equal to 0 numbers that represents the distance in point units. If you want for the handler to [activate](/docs/2.x/under-the-hood/state#active) for the movement in one particular direction use [`minOffsetY`](#minoffsety) instead. ### `avgTouches` (Android only) @@ -130,7 +130,7 @@ Enables two-finger gestures on supported devices, for example iPads with trackpa ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `PanGestureHandler`: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `PanGestureHandler`: ### `translationX` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pinch-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pinch-gh.md index adf4ae9442..c1b52f36d8 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pinch-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pinch-gh.md @@ -6,11 +6,11 @@ sidebar_position: 10 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A continuous gesture handler that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. -The handler [activates](/docs/under-the-hood/state#active) when fingers are placed on the screen and change their position. +The handler [activates](/docs/2.x/under-the-hood/state#active) when fingers are placed on the screen and change their position. Gesture callback can be used for continuous tracking of the pinch gesture. It provides information about velocity, anchor (focal) point of gesture and scale. The distance between the fingers is reported as a scale factor. At the beginning of the gesture, the scale factor is 1.0. As the distance between the two fingers increases, the scale factor increases proportionally. @@ -22,11 +22,11 @@ The handler is implemented using [UIPinchGestureRecognizer](https://developer.ap ## Properties -Properties provided to `PinchGestureHandler` do not extend [common set of properties from base handler class](/docs/gesture-handlers/common-gh#properties). +Properties provided to `PinchGestureHandler` do not extend [common set of properties from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `PinchGestureHandler`: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `PinchGestureHandler`: ### `scale` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/rotation-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/rotation-gh.md index b6b20f931c..c43f798163 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/rotation-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/rotation-gh.md @@ -6,12 +6,12 @@ sidebar_position: 8 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A continuous gesture handler that can recognize a rotation gesture and track its movement. -The handler [activates](/docs/under-the-hood/state#active) when fingers are placed on the screen and change position in a proper way. +The handler [activates](/docs/2.x/under-the-hood/state#active) when fingers are placed on the screen and change position in a proper way. Gesture callback can be used for continuous tracking of the rotation gesture. It provides information about the gesture such as the amount rotated, the focal point of the rotation (anchor), and its instantaneous velocity. @@ -19,11 +19,11 @@ The handler is implemented using [UIRotationGestureRecognizer](https://developer ## Properties -Properties provided to `RotationGestureHandler` do not extend [common set of properties from base handler class](/docs/gesture-handlers/common-gh#properties). +Properties provided to `RotationGestureHandler` do not extend [common set of properties from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `RotationGestureHandler`: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `RotationGestureHandler`: ### `rotation` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/tap-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/tap-gh.md index c151632c03..349c1fab5f 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/tap-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/tap-gh.md @@ -6,7 +6,7 @@ sidebar_position: 6 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A discrete gesture handler that recognizes one or many taps. @@ -16,15 +16,15 @@ The fingers involved in these gestures must not move significantly from their in The required number of taps and allowed distance from initial position may be configured. For example, you might configure tap gesture recognizers to detect single taps, double taps, or triple taps. -In order for a handler to [activate](/docs/under-the-hood/state#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](/docs/under-the-hood/state#active), it will [END](/docs/under-the-hood/state#end). +In order for a handler to [activate](/docs/2.x/under-the-hood/state#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](/docs/2.x/under-the-hood/state#active), it will [END](/docs/2.x/under-the-hood/state#end). ## Properties -See [set of properties inherited from base handler class](/docs/gesture-handlers/common-gh#properties). Below is a list of properties specific to the `TapGestureHandler` component: +See [set of properties inherited from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). Below is a list of properties specific to the `TapGestureHandler` component: ### `minPointers` -Minimum number of pointers (fingers) required to be placed before the handler [activates](/docs/under-the-hood/state#active). Should be a positive integer. The default value is 1. +Minimum number of pointers (fingers) required to be placed before the handler [activates](/docs/2.x/under-the-hood/state#active). Should be a positive integer. The default value is 1. ### `maxDurationMs` @@ -36,23 +36,23 @@ Maximum time, expressed in milliseconds, that can pass before the next tap — i ### `numberOfTaps` -Number of tap gestures required to [activate](/docs/under-the-hood/state#active) the handler. The default value is 1. +Number of tap gestures required to [activate](/docs/2.x/under-the-hood/state#active) the handler. The default value is 1. ### `maxDeltaX` -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture. If the finger travels further than the defined distance along the X axis and the handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. +Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture. If the finger travels further than the defined distance along the X axis and the handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active), it will fail to recognize the gesture. ### `maxDeltaY` -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture. If the finger travels further than the defined distance along the Y axis and the handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. +Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture. If the finger travels further than the defined distance along the Y axis and the handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active), it will fail to recognize the gesture. ### `maxDist` -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture. If the finger travels further than the defined distance and the handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. +Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture. If the finger travels further than the defined distance and the handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active), it will fail to recognize the gesture. ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to the `TapGestureHandler` component: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to the `TapGestureHandler` component: ### `x` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-config.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-config.md index 71ca8db252..f829d626e9 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-config.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-config.md @@ -2,4 +2,4 @@ ### `manualActivation(value: boolean)` -When `true` the handler will not activate by itself even if its activation criteria are met. Instead you can manipulate its state using [state manager](/docs/gestures/state-manager/). +When `true` the handler will not activate by itself even if its activation criteria are met. Instead you can manipulate its state using [state manager](/docs/2.x/gestures/state-manager/). diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-config.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-config.md index 2e2fb6d425..6a39d4cb75 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-config.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-config.md @@ -3,19 +3,19 @@ ### `enabled(value: boolean)` Indicates whether the given handler should be analyzing stream of touch events or not. -When set to `false` we can be sure that the handler's state will **never** become [`ACTIVE`](/docs/fundamentals/states-events#active). -If the value gets updated while the handler already started recognizing a gesture, then the handler's state it will immediately change to [`FAILED`](/docs/fundamentals/states-events#failed) or [`CANCELLED`](/docs/fundamentals/states-events#cancelled) (depending on its current state). +When set to `false` we can be sure that the handler's state will **never** become [`ACTIVE`](/docs/2.x/fundamentals/states-events#active). +If the value gets updated while the handler already started recognizing a gesture, then the handler's state it will immediately change to [`FAILED`](/docs/2.x/fundamentals/states-events#failed) or [`CANCELLED`](/docs/2.x/fundamentals/states-events#cancelled) (depending on its current state). Default value is `true`. ### `shouldCancelWhenOutside(value: boolean)` -When `true` the handler will [cancel](/docs/fundamentals/states-events#cancelled) or [fail](/docs/fundamentals/states-events#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. +When `true` the handler will [cancel](/docs/2.x/fundamentals/states-events#cancelled) or [fail](/docs/2.x/fundamentals/states-events#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. Default value of this property is different depending on the handler type. -Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGesture`](/docs/gestures/long-press-gesture) and [`TapGesture`](/docs/gestures/tap-gesture) which default to `true`. +Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGesture`](/docs/2.x/gestures/long-press-gesture) and [`TapGesture`](/docs/2.x/gestures/tap-gesture) which default to `true`. ### `hitSlop(settings)` -This parameter enables control over what part of the connected view area can be used to [begin](/docs/fundamentals/states-events#began) recognizing the gesture. +This parameter enables control over what part of the connected view area can be used to [begin](/docs/2.x/fundamentals/states-events#began) recognizing the gesture. When a negative number is provided the bounds of the view will reduce the area by the given number of points in each of the sides evenly. Instead you can pass an object to specify how each boundary side should be reduced by providing different number of points for `left`, `right`, `top` or `bottom` sides. @@ -39,7 +39,7 @@ Sets a `testID` property for gesture object, allowing for querying for it in tes ### `cancelsTouchesInView(value)` (**iOS only**) Accepts a boolean value. -When `true`, the gesture will cancel touches for native UI components (`UIButton`, `UISwitch`, etc) it's attached to when it becomes [`ACTIVE`](/docs/fundamentals/states-events#active). +When `true`, the gesture will cancel touches for native UI components (`UIButton`, `UISwitch`, etc) it's attached to when it becomes [`ACTIVE`](/docs/2.x/fundamentals/states-events#active). Default value is `true`. ### `runOnJS(value: boolean)` @@ -51,7 +51,7 @@ Defaults to `false`. Adds a gesture that should be recognized simultaneously with this one. -**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](/docs/fundamentals/gesture-composition). [`GestureDetector`](/docs/gestures/gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. +**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](/docs/2.x/fundamentals/gesture-composition). [`GestureDetector`](/docs/2.x/gestures/gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. ### `requireExternalGestureToFail(otherGesture1, otherGesture2, ...)` @@ -61,7 +61,7 @@ Adds a relation requiring another gesture to fail, before this one can activate. Adds a relation that makes other gestures wait with activation until this gesture fails (or doesn't start at all). -**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](/docs/fundamentals/gesture-composition).[`GestureDetector`](/docs/gestures/gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. +**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](/docs/2.x/fundamentals/gesture-composition).[`GestureDetector`](/docs/2.x/gestures/gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. ### `activeCursor(value)` (Web only) diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-event-data.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-event-data.md index 6d6767d639..674f2fb478 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-event-data.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-event-data.md @@ -2,7 +2,7 @@ ### `state` -Current [state](/docs/fundamentals/states-events) of the handler. Expressed as one of the constants exported under `State` object by the library. +Current [state](/docs/2.x/fundamentals/states-events) of the handler. Expressed as one of the constants exported under `State` object by the library. ### `numberOfPointers` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/composed-gestures.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/composed-gestures.md index f9fd18f36a..5eb0ef45c5 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/composed-gestures.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/composed-gestures.md @@ -5,7 +5,7 @@ sidebar_label: Composed gestures sidebar_position: 13 --- -Composed gestures (`Race`, `Simultaneous`, `Exclusive`) provide a simple way of building relations between gestures. See [Gesture Composition](/docs/fundamentals/gesture-composition) for more details. +Composed gestures (`Race`, `Simultaneous`, `Exclusive`) provide a simple way of building relations between gestures. See [Gesture Composition](/docs/2.x/fundamentals/gesture-composition) for more details. ## Reference diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/fling-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/fling-gesture.md index fef89e4868..58a6812429 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/fling-gesture.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/fling-gesture.md @@ -30,8 +30,8 @@ import BaseEventConfig from './\_shared/base-gesture-config.md'; import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; A discrete gesture that activates when the movement is sufficiently long and fast. -Gesture gets [ACTIVE](/docs/fundamentals/states-events#active) when movement is sufficiently long and it does not take too much time. -When gesture gets activated it will turn into [END](/docs/fundamentals/states-events#end) state when finger is released. +Gesture gets [ACTIVE](/docs/2.x/fundamentals/states-events#active) when movement is sufficiently long and it does not take too much time. +When gesture gets activated it will turn into [END](/docs/2.x/fundamentals/states-events#end) state when finger is released. The gesture will fail to recognize if the finger is lifted before being activated.
diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/force-touch-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/force-touch-gesture.md index d3f85e6edd..8227c7dea2 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/force-touch-gesture.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/force-touch-gesture.md @@ -16,7 +16,7 @@ import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; import BaseContinuousEventCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; A continuous gesture that recognizes force of a touch. It allows for tracking pressure of touch on some iOS devices. -The gesture [activates](/docs/fundamentals/states-events#active) when pressure of touch is greater than or equal to `minForce`. It fails if pressure is greater than `maxForce`. +The gesture [activates](/docs/2.x/fundamentals/states-events#active) when pressure of touch is greater than or equal to `minForce`. It fails if pressure is greater than `maxForce`. Gesture callback can be used for continuous tracking of the touch pressure. It provides information for one finger (the first one). At the beginning of the gesture, the pressure factor is 0.0. As the pressure increases, the pressure factor increases proportionally. The maximum pressure is 1.0. @@ -47,11 +47,11 @@ function App() { ### `minForce(value: number)` -A minimal pressure that is required before gesture can [activate](/docs/fundamentals/states-events#active). Should be a value from range `[0.0, 1.0]`. Default is `0.2`. +A minimal pressure that is required before gesture can [activate](/docs/2.x/fundamentals/states-events#active). Should be a value from range `[0.0, 1.0]`. Default is `0.2`. ### `maxForce(value: number)` -A maximal pressure that could be applied for gesture. If the pressure is greater, gesture [fails](/docs/fundamentals/states-events#failed). Should be a value from range `[0.0, 1.0]`. +A maximal pressure that could be applied for gesture. If the pressure is greater, gesture [fails](/docs/2.x/fundamentals/states-events#failed). Should be a value from range `[0.0, 1.0]`. ### `feedbackOnActivation(value: boolean)` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture-detector.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture-detector.md index cd8ca83a7d..a4184af36b 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture-detector.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture-detector.md @@ -35,7 +35,7 @@ A gesture object containing the configuration and callbacks. Can be any of the b :::info GestureDetector will decide whether to use Reanimated to process provided gestures based on callbacks they have. If any of the callbacks is a worklet, tools provided by the Reanimated will be utilized bringing ability to handle gestures synchronously. -Starting with Reanimated 2.3.0 Gesture Handler will provide a [StateManager](/docs/gestures/state-manager) in the [touch events](/docs/gestures/touch-events) that allows for managing the state of the gesture. +Starting with Reanimated 2.3.0 Gesture Handler will provide a [StateManager](/docs/2.x/gestures/state-manager) in the [touch events](/docs/2.x/gestures/touch-events) that allows for managing the state of the gesture. ::: ### `userSelect` (Web only) @@ -66,7 +66,9 @@ Specifies whether context menu should be enabled after clicking on underlying vi - {/* Don't do this! */} + + {' '} + {/* Don't do this! */} diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture.md index 08bc5888d7..8d9202e4e7 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture.md @@ -26,43 +26,43 @@ function App() { ### Gesture.Tap() -Creates a new instance of [`TapGesture`](/docs/gestures/tap-gesture.md) with its default config and no callbacks. +Creates a new instance of [`TapGesture`](/docs/2.x/gestures/tap-gesture.md) with its default config and no callbacks. ### Gesture.Pan() -Creates a new instance of [`PanGesture`](/docs/gestures/pan-gesture.md) with its default config and no callbacks. +Creates a new instance of [`PanGesture`](/docs/2.x/gestures/pan-gesture.md) with its default config and no callbacks. ### Gesture.LongPress() -Creates a new instance of [`LongPressGesture`](/docs/gestures/long-press-gesture.md) with its default config and no callbacks. +Creates a new instance of [`LongPressGesture`](/docs/2.x/gestures/long-press-gesture.md) with its default config and no callbacks. ### Gesture.Fling() -Creates a new instance of [`FlingGesture`](/docs/gestures/fling-gesture.md) with its default config and no callbacks. +Creates a new instance of [`FlingGesture`](/docs/2.x/gestures/fling-gesture.md) with its default config and no callbacks. ### Gesture.Pinch() -Creates a new instance of [`PinchGesture`](/docs/gestures/pinch-gesture.md) with its default config and no callbacks. +Creates a new instance of [`PinchGesture`](/docs/2.x/gestures/pinch-gesture.md) with its default config and no callbacks. ### Gesture.Rotation() -Creates a new instance of [`RotationGesture`](/docs/gestures/rotation-gesture.md) with its default config and no callbacks. +Creates a new instance of [`RotationGesture`](/docs/2.x/gestures/rotation-gesture.md) with its default config and no callbacks. ### Gesture.Hover() -Creates a new instance of [`HoverGesture`](/docs/gestures/hover-gesture.md) with its default config and no callbacks. +Creates a new instance of [`HoverGesture`](/docs/2.x/gestures/hover-gesture.md) with its default config and no callbacks. ### Gesture.ForceTouch() -Creates a new instance of [`ForceTouchGesture`](/docs/gestures/force-touch-gesture.md) with its default config and no callbacks. +Creates a new instance of [`ForceTouchGesture`](/docs/2.x/gestures/force-touch-gesture.md) with its default config and no callbacks. ### Gesture.Manual() -Creates a new instance of [`ManualGesture`](/docs/gestures/manual-gesture.md) with its default config and no callbacks. +Creates a new instance of [`ManualGesture`](/docs/2.x/gestures/manual-gesture.md) with its default config and no callbacks. ### Gesture.Native() -Creates a new instance of [`NativeGesture`](/docs/gestures/native-gesture.md) with its default config and no callbacks. +Creates a new instance of [`NativeGesture`](/docs/2.x/gestures/native-gesture.md) with its default config and no callbacks. ### Gesture.Race(gesture1, gesture2, gesture3, ...): ComposedGesture diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/hover-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/hover-gesture.md index 5ad5628dca..6b794fd4bf 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/hover-gesture.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/hover-gesture.md @@ -59,10 +59,9 @@ function App() { } ``` - ## Remarks -- Don't rely on `Hover` gesture to continue after the mouse button is clicked or the stylus touches the screen. If you want to handle both cases, [compose](/docs/fundamentals/gesture-composition) it with [`Pan` gesture](/docs/gestures/pan-gesture). +- Don't rely on `Hover` gesture to continue after the mouse button is clicked or the stylus touches the screen. If you want to handle both cases, [compose](/docs/2.x/fundamentals/gesture-composition) it with [`Pan` gesture](/docs/2.x/gestures/pan-gesture). ## Config @@ -95,11 +94,11 @@ Defaults to `HoverEffect.None` ### `x` -X coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). Expressed in point units. +X coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector). Expressed in point units. ### `y` -Y coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). Expressed in point units. +Y coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector). Expressed in point units. ### `absoluteX` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/long-press-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/long-press-gesture.md index f92814e255..61f5431703 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/long-press-gesture.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/long-press-gesture.md @@ -30,8 +30,8 @@ import BaseEventConfig from './\_shared/base-gesture-config.md'; import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; A discrete gesture that activates when the corresponding view is pressed for a sufficiently long time. -This gesture's state will turn into [END](/docs/fundamentals/states-events#end) immediately after the finger is released. -The gesture will fail to recognize a touch event if the finger is lifted before the [minimum required time](/docs/gestures/long-press-gesture#mindurationvalue-number) or if the finger is moved further than the [allowable distance](/docs/gestures/long-press-gesture#maxdistancevalue-number). +This gesture's state will turn into [END](/docs/2.x/fundamentals/states-events#end) immediately after the finger is released. +The gesture will fail to recognize a touch event if the finger is lifted before the [minimum required time](/docs/2.x/gestures/long-press-gesture#mindurationvalue-number) or if the finger is moved further than the [allowable distance](/docs/2.x/gestures/long-press-gesture#maxdistancevalue-number).