Upgrading to the new API introduced in Gesture Handler 3

Migrating gestures

The most important change brought by the Gesture Handler 3 is the new hook API. Migration is pretty straightforward. Instead of calling builder methods, everything is passed as a configuration object.

RNGH 2

const gesture = Gesture.Pan()
.onBegin(() => {
  console.log('Pan!');
})
.minDistance(25);

RNGH 3

const gesture = usePanGesture({
    onBegin: () => {
      console.log('Pan!');
    },
    minDistance: 25,
  });

ForceTouch gesture is not available in hook API.

Full changes

RNGH2	RNGH3
Gesture.Pan()	usePanGesture()
Gesture.Tap()	useTapGesture()
Gesture.LongPress()	useLongPressGesture()
Gesture.Rotation()	useRotationGesture()
Gesture.Pinch()	usePinchGesture()
Gesture.Fling()	useFlingGesture()
Gesture.Hover()	useHoverGesture()
Gesture.Native()	useNativeGesture()
Gesture.Manual()	useManualGesture()
Gesture.ForceTouch()	Not available in hook API

Renamed callbacks

In Gesture Handler 3 some of the callbacks were renamed, namely:

RNGH2	RNGH3
onStart	onActivate
onEnd	onDeactivate
onTouchesCancelled	onTouchesCancel

Here is comparison of the two APIs:

RNGH 2

const gesture = Gesture.Pan()
.onStart(() => {
  console.log('Pan started!');
})
.onEnd(() => {
  console.log('Pan ended!');
})
.onTouchesCancelled(() => {
  console.log('Pan touches cancelled!');
});

RNGH 3

const gesture = usePanGesture({
onActivate: () => {
  console.log('Pan activated!');
},
onDeactivate: () => {
  console.log('Pan deactivated!');
},
onTouchesCancel: () => {
  console.log('Pan touches cancelled!');
},
});

onChange

onChange callback has been removed, and its functionality has been integrated into onUpdate. You can now access change* properties in onUpdate callback.

RNGH 2

const pan = Gesture.Pan().onChange((e) => {
console.log(e.changeX);
});

RNGH 3

const pan = usePanGesture({
onUpdate: (e) => {
  console.log(e.changeX);
},
});

state & oldState

The state and oldState properties are no longer available in event objects. Tracking state changes can now only be accomplished using the appropriate callbacks.

Event types

The types of events have been unified for all callbacks. Each event falls into one of two categories: GestureEvent for gesture callbacks, or GestureTouchEvent for TouchEvent callbacks.

StateManager

In Gesture Handler 3, stateManager is no longer passed to TouchEvent callbacks. Instead, you should use the global GestureStateManager.

RNGH 2

const manual = Gesture.Manual().onTouchesDown((e, stateManager ) => {
stateManager.activate();
});

RNGH 3

const manual = useManualGesture({
onTouchesDown: (e) => {
  GestureStateManager.activate(e.handlerTag);
},
});

Migrating relations

Composed gestures

Previously, composed gestures were created using Gesture object. In Gesture Handler 3, relations are set up using relation hooks.

RNGH 2

const pan1 = Gesture.Pan();
const pan2 = Gesture.Pan();

const gesture = Gesture.Simultaneous(pan1, pan2);

RNGH 3

const pan1 = usePanGesture({});
const pan2 = usePanGesture({});

const gesture = useSimultaneousGestures(pan1, pan2);

Full changes are as follows:

RNGH2	RNGH3
Gesture.Race()	useCompetingGestures()
Gesture.Simultaneous()	useSimultaneousGestures()
Gesture.Exclusive()	useExclusiveGestures()

Cross components relations properties

Properties used to define cross-components interactions were renamed.

RNGH 2

const pan1 = Gesture.Pan();
const pan2 =
  Gesture.Pan().requireExternalGestureToFail(pan1);

RNGH 3

const pan1 = usePanGesture({});
const pan2 = usePanGesture({
requireToFail: pan1,
});

Full changes are as follows:

RNGH2	RNGH3
gesture.simultaneousWithExternalGesture	gesture.simultaneousWith
gesture.requireExternalGestureToFail	gesture.requireToFail
gesture.blocksExternalGesture	gesture.block

Migrating components relying on view hierarchy

Certain components, such as SVG, depend on the view hierarchy to function correctly. In Gesture Handler 3, GestureDetector disrupts these hierarchies. To resolve this issue, two new detectors have been introduced: InterceptingGestureDetector and VirtualGestureDetector.

Detectors order

VirtualGestureDetector has to be a descendant of InterceptingGestureDetector.

Migrating SVG

In Gesture Handler 2 it was possible to use GestureDetector directly on SVG. In Gesture Handler 3, the correct way to interact with SVG is to use InterceptingGestureDetector and VirtualGestureDetector.

RNGH 2

<GestureDetector gesture={containerTap}>
<Svg>
  <GestureDetector gesture={circleTap}>
    <Circle />
  </GestureDetector>
</Svg>
</GestureDetector>

RNGH 3

<InterceptingGestureDetector gesture={containerTap}>
<Svg>
  <VirtualGestureDetector gesture={circleTap}>
    <Circle />
  </VirtualGestureDetector>
</Svg>
</InterceptingGestureDetector>

Old components

Buttons

The implementation of buttons has been updated, resolving most button-related issues. They have also been internally rewritten to utilize the new hook API. The original button components are still accessible but have been renamed with the prefix Legacy, e.g., RectButton is now available as LegacyRectButton.

Although the legacy JS implementation of the buttons is still available, they also use the new host component internally.

Legacy buttons

RNGH2	RNGH3
RawButton	LegacyRawButton
BaseButton	LegacyBaseButton
RectButton	LegacyRectButton
BorderlessButton	LegacyBorderlessButton

Other components

Other components have also been internally rewritten using the new hook API but are exported under their original names, so no changes are necessary on your part. However, if you need to use the previous implementation for any reason, the old components are also available and are prefixed with Legacy, e.g., ScrollView is now available as LegacyScrollView.

Legacy components

RNGH2	RNGH3
ScrollView	LegacyScrollView
FlatList	LegacyFlatList
RefreshControl	LegacyRefreshControl
Switch	LegacySwitch
TextInput	LegacyTextInput
DrawerLayoutAndroid	LegacyDrawerLayoutAndroid

Replaced types

Most of the types, like TapGesture, are still present in Gesture Handler 3. However, they are now used in new hook API. Types for old API now have Legacy prefix, e.g. TapGesture becomes LegacyTapGesture.

Legacy types

RNGH2	RNGH3
PanGesture	LegacyPanGesture
TapGesture	LegacyTapGesture
LongPressGesture	LegacyLongPressGesture
RotationGesture	LegacyRotationGesture
PinchGesture	LegacyPinchGesture
FlingGesture	LegacyFlingGesture
HoverGesture	LegacyHoverGesture
NativeGesture	LegacyNativeGesture
ManualGesture	LegacyManualGesture
ForceTouchGesture	LegacyForceTouchGesture
ComposedGesture	LegacyComposedGesture
RaceGesture	LegacyRaceGesture
SimultaneousGesture	LegacySimultaneousGesture
ExclusiveGesture	LegacyExclusiveGesture
RawButtonProps	LegacyRawButtonProps
BaseButtonProps	LegacyBaseButtonProps
RectButtonProps	LegacyRectButtonProps
BorderlessButtonProps	LegacyBorderlessButtonProps