Update docs

j-piasecki · j-piasecki · commit 135d24d23ad1 · 2026-04-14T13:44:15.000+02:00
diff --git a/packages/docs-gesture-handler/docs/fundamentals/callbacks-events.mdx b/packages/docs-gesture-handler/docs/fundamentals/callbacks-events.mdx
@@ -55,18 +55,18 @@ Called each time a pointer tracked by the gesture changes state, typically due t
 ### onDeactivate
 
 ```ts
-onDeactivate: (event: GestureEvent<HandlerData>, didSucceed: boolean) => void
+onDeactivate: (event: GestureEndEvent<HandlerData>) => void
 ```
 
-Called when handler stops recognizing gestures, but only if the handler activated. It is called before `onFinalize`. If the handler was interrupted, the `didSucceed` argument is set to `false`. Otherwise it is set to `true`.
+Called when handler stops recognizing gestures, but only if the handler activated. It is called before `onFinalize`. The event object contains a `canceled` property — if the handler was interrupted or failed to recognize the gesture, `canceled` is set to `true`. Otherwise it is set to `false`.
 
 ### onFinalize
 
 ```ts
-onFinalize: (event: GestureEvent<HandlerData>, didSucceed: boolean) => void
+onFinalize: (event: GestureEndEvent<HandlerData>) => void
 ```
 
-Called when handler stops recognizing gestures. If the handler managed to activate, the `didSucceed` argument is set to `true` and `onFinalize` will be called right after `onDeactivate`. Otherwise it is set to `false`.
+Called when handler stops recognizing gestures. The event object contains a `canceled` property — if the handler failed to activate or was interrupted, `canceled` is set to `true`. If the handler managed to activate and completed successfully, `canceled` is set to `false` and `onFinalize` will be called right after `onDeactivate`.
 
 ### onTouchesDown
 
@@ -107,14 +107,18 @@ Called when there will be no more information about this pointer. It may be call
 <CollapsibleCode 
 label="Show composed types definitions"
 expandedLabel="Hide composed types definitions"
-lineBounds={[0, 4]}
+lineBounds={[0, 8]}
 src={`
 export type GestureEvent<HandlerData> = {
   handlerTag: number;
   numberOfPointers: number;
   pointerType: PointerType;
 } & HandlerData;
 
+export type GestureEndEvent<HandlerData> = {
+  canceled: boolean;
+} & GestureEvent<HandlerData>;
+
 export enum PointerType {
   TOUCH,
   STYLUS,
@@ -126,6 +130,10 @@ export enum PointerType {
 
 `GestureEvent` contains properties common to all gestures (`handlerTag`, `numberOfPointers`, `pointerType`) along with gesture-specific data defined in each gesture's documentation.
 
+### GestureEndEvent
+
+`GestureEndEvent` extends `GestureEvent` with a `canceled` property. It is used in the [`onDeactivate`](#ondeactivate) and [`onFinalize`](#onfinalize) callbacks. When `canceled` is `true`, the gesture was interrupted or failed to activate. When `false`, the gesture completed successfully.
+
 ### TouchEvent
 
 <CollapsibleCode 
diff --git a/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-callbacks.mdx b/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-callbacks.mdx
@@ -24,21 +24,21 @@ Set the callback that is being called when the gesture is recognized by the hand
 
 {
 <CodeBlock className="language-ts">
-    {`onDeactivate: (event: ${props.gesture}HandlerData, didSucceed: boolean) => void`}
+    {`onDeactivate: (event: ${props.gesture}HandlerData & { canceled: boolean }) => void`}
 </CodeBlock>
 }
 
-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.
+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. The event object contains a `canceled` property — if the gesture was interrupted, `canceled` is set to `true`. Otherwise it is set to `false`.
 
 ### onFinalize
 
 {
 <CodeBlock className="language-ts">
-    {`onFinalize: (event: ${props.gesture}HandlerData, didSucceed: boolean) => void`}
+    {`onFinalize: (event: ${props.gesture}HandlerData & { canceled: boolean }) => void`}
 </CodeBlock>
 }
 
-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.
+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. The event object contains a `canceled` property — if the gesture failed to activate or was interrupted, `canceled` is set to `true`. Otherwise it is set to `false`.
 
 ### onTouchesDown
 
diff --git a/packages/docs-gesture-handler/docs/guides/upgrading-to-3.mdx b/packages/docs-gesture-handler/docs/guides/upgrading-to-3.mdx
@@ -92,6 +92,32 @@ code2={
 `}
 />
 
+### canceled instead of didSucceed
+
+In RNGH2, `onEnd` and `onFinalize` received a second `success` boolean parameter. In RNGH3, this has been replaced with a `canceled` property on the event object itself. Note that the logic is inverted — `canceled: true` corresponds to the old `success: false`.
+
+<CodeComparison
+label1={"RNGH 2"}
+label2={"RNGH 3"}
+code1={
+`const gesture = Gesture.Tap()
+  .onEnd((event, success) => {
+    if (success) {
+      console.log('Gesture succeeded!');
+    }
+  });
+`}
+code2={
+`const gesture = useTapGesture({
+  onDeactivate: (event) => {
+    if (!event.canceled) {
+      console.log('Gesture succeeded!');
+    }
+  },
+});
+`}
+/>
+
 ### onChange
 
 `onChange` callback has been removed, and its functionality has been integrated into `onUpdate`. You can now access `change*` properties in `onUpdate` callback.
diff --git a/packages/docs-gesture-handler/docs/under-the-hood/state.md b/packages/docs-gesture-handler/docs/under-the-hood/state.md
@@ -14,6 +14,6 @@ States manage the internal recognition process. You can hook into these transiti
 | **`UNDETERMINED`** | The default initial state of every handler.                                              | —                                                                                                                                                                                                                                                                                  |
 | **`BEGAN`**        | The handler has started receiving touch data but hasn't yet met the activation criteria. | [`onBegin`](/docs/fundamentals/callbacks-events#onbegin)                                                                                                                                                                                                                           |
 | **`ACTIVE`**       | The gesture is recognized and activation criteria are met.                               | [`onActivate`](/docs/fundamentals/callbacks-events#onactivate) when it first transitions into the `ACTIVE` state. <br /><br /> [`onUpdate`](/docs/fundamentals/callbacks-events#onupdate) when it has new data about the gesture.                                                  |
-| **`END`**          | The user successfully completed the gesture.                                             | [`onDeactivate`](/docs/fundamentals/callbacks-events#ondeactivate) with `didSucceed` parameter set to `true`. <br/><br/> [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) with `didSucceed` parameter set to `true`.                                                 |
-| **`FAILED`**       | The handler failed to recognize the gesture.                                             | [`onDeactivate`](/docs/fundamentals/callbacks-events#ondeactivate) if the gesture was in `ACTIVE` state before. `didSucceed` parameter will be set to `false` <br/><br/> [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) with `didSucceed` parameter set to `false`. |
-| **`CANCELLED`**    | The system interrupted the gesture.                                                      | [`onDeactivate`](/docs/fundamentals/callbacks-events#ondeactivate) if the gesture was in `ACTIVE` state before. `didSucceed` parameter will be set to `false` <br/><br/> [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) with `didSucceed` parameter set to `false`. |
+| **`END`**          | The user successfully completed the gesture.                                             | [`onDeactivate`](/docs/fundamentals/callbacks-events#ondeactivate) with `event.canceled` set to `false`. <br/><br/> [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) with `event.canceled` set to `false`.                                                 |
+| **`FAILED`**       | The handler failed to recognize the gesture.                                             | [`onDeactivate`](/docs/fundamentals/callbacks-events#ondeactivate) if the gesture was in `ACTIVE` state before, with `event.canceled` set to `true`. <br/><br/> [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) with `event.canceled` set to `true`. |
+| **`CANCELLED`**    | The system interrupted the gesture.                                                      | [`onDeactivate`](/docs/fundamentals/callbacks-events#ondeactivate) if the gesture was in `ACTIVE` state before, with `event.canceled` set to `true`. <br/><br/> [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) with `event.canceled` set to `true`. |
diff --git a/skills/gesture-handler-3-migration/SKILL.md b/skills/gesture-handler-3-migration/SKILL.md
@@ -40,6 +40,20 @@ In Gesture Handler 3 some of the callbacks were renamed, namely:
 - `onEnd` -> `onDeactivate`
 - `onTouchesCancelled` -> `onTouchesCancel`
 
+The `onDeactivate` and `onFinalize` callbacks no longer receive a second `didSucceed`/`success` boolean parameter. Instead, the event object now contains a `canceled` property. Note that the logic is inverted — `canceled: true` corresponds to the old `success: false`.
+
+```jsx
+// Old (RNGH2)
+.onEnd((event, success) => {
+  if (success) { /* gesture succeeded */ }
+})
+
+// New (RNGH3)
+onDeactivate: (event) => {
+  if (!event.canceled) { /* gesture succeeded */ }
+}
+```
+
 In the hooks API `onChange` is no longer available. Instead the `*change*` properties were moved to the event available inside `onUpdate`.
 
 All callbacks of a gesture are now using the same type:

Original file line number	Diff line number	Diff line change
`@@ -24,21 +24,21 @@ Set the callback that is being called when the gesture is recognized by the hand`
`24`	`24`
`25`	`25`	`{`
`26`	`26`	`<CodeBlock className="language-ts">`
`27`		- {`onDeactivate: (event: ${props.gesture}HandlerData, didSucceed: boolean) => void`}
	`27`	+ {`onDeactivate: (event: ${props.gesture}HandlerData & { canceled: boolean }) => void`}
`28`	`28`	`</CodeBlock>`
`29`	`29`	`}`
`30`	`30`
`31`		`-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.`
	`31`	+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. The event object contains a `canceled` property — if the gesture was interrupted, `canceled` is set to `true`. Otherwise it is set to `false`.
`32`	`32`
`33`	`33`	`### onFinalize`
`34`	`34`
`35`	`35`	`{`
`36`	`36`	`<CodeBlock className="language-ts">`
`37`		- {`onFinalize: (event: ${props.gesture}HandlerData, didSucceed: boolean) => void`}
	`37`	+ {`onFinalize: (event: ${props.gesture}HandlerData & { canceled: boolean }) => void`}
`38`	`38`	`</CodeBlock>`
`39`	`39`	`}`
`40`	`40`
`41`		`-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.`
	`41`	+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. The event object contains a `canceled` property — if the gesture failed to activate or was interrupted, `canceled` is set to `true`. Otherwise it is set to `false`.
`42`	`42`
`43`	`43`	`### onTouchesDown`
`44`	`44`