How does react-native-gesture-handler work?

The built-in touch system works for simple taps and pans, but complex interactions such as swipes, pinch and simultaneous gestures need a dedicated recogniser. react-native-gesture-handler provides one and integrates with Reanimated worklets for UI-thread updates.

import { Gesture, GestureDetector } from "react-native-gesture-handler";
import Animated, { useAnimatedStyle, useSharedValue, withSpring } from "react-native-reanimated";

export function Draggable() {
  const x = useSharedValue(0);
  const pan = Gesture.Pan().onChange((event) => {
    x.value += event.changeX;
  }).onEnd(() => {
    x.value = withSpring(0);
  });
  const style = useAnimatedStyle(() => ({ transform: [{ translateX: x.value }] }));

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[{ width: 80, height: 80 }, style]} />
    </GestureDetector>
  );
}

Composition and conflicts

• Gesture.Race for whichever gesture activates first
• Gesture.Simultaneous for pinch and pan together
• Gesture.Exclusive when one gesture should take priority
• blocksExternalGesture and requireExternalGestureToFail to coordinate with scroll views
• GestureHandlerRootView must wrap the app at the root

Gestures inside a ScrollView are a common source of conflict. A horizontal swipe on a row may be stolen by vertical scrolling, or the list may not scroll at all. Use the composition helpers and test on both platforms, because the native recognisers behave differently.