or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-components.mdbuttons.mdcomponents.mdconstants.mdevents.mdgestures.mdindex.mdsetup.md
tile.json

tessl/npm-react-native-gesture-handler

Declarative API exposing platform native touch and gesture system to React Native

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-native-gesture-handler@2.28.x

To install, run

npx @tessl/cli install tessl/npm-react-native-gesture-handler@2.28.0

index.mddocs/

React Native Gesture Handler

React Native Gesture Handler is a comprehensive native-driven gesture management system for React Native applications. It moves gesture recognition and tracking from JavaScript to the native UI thread, providing high-performance touch interactions, smooth animations, and cross-platform support for iOS, Android, and Web.

Package Information

  • Package Name: react-native-gesture-handler
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install react-native-gesture-handler

Core Imports

import {
  GestureDetector,
  Gesture,
  GestureHandlerRootView,
} from "react-native-gesture-handler";

For CommonJS:

const {
  GestureDetector,
  Gesture,
  GestureHandlerRootView,
} = require("react-native-gesture-handler");

Basic Usage

import React from "react";
import { View } from "react-native";
import {
  GestureDetector,
  Gesture,
  GestureHandlerRootView,
} from "react-native-gesture-handler";

export default function App() {
  const tapGesture = Gesture.Tap()
    .numberOfTaps(2)
    .onEnd(() => {
      console.log("Double tap detected!");
    });

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <GestureDetector gesture={tapGesture}>
        <View style={{ width: 100, height: 100, backgroundColor: "red" }} />
      </GestureDetector>
    </GestureHandlerRootView>
  );
}

Architecture

React Native Gesture Handler provides two main APIs:

  • Modern Gesture API: Recommended approach using GestureDetector and Gesture factory for creating composable, performant gestures
  • Legacy Handler Components: Deprecated individual gesture handler components (TapGestureHandler, PanGestureHandler, etc.)
  • Enhanced Components: Drop-in replacements for React Native components with gesture support
  • Native Thread Processing: Gestures are processed on the native UI thread for maximum performance
  • Reanimated Integration: Seamless integration with react-native-reanimated for smooth animations

Capabilities

Setup and Root Components

Essential components and setup required for gesture handlers to function properly in React Native applications.

// Root component required for gestures to work
function GestureHandlerRootView(props: {
  style?: StyleProp<ViewStyle>;
  children?: React.ReactNode;
}): JSX.Element;

// Legacy HOC for wrapping app root (deprecated)
function gestureHandlerRootHOC<T>(
  Component: React.ComponentType<T>,
  containerStyles?: StyleProp<ViewStyle>
): React.ComponentType<T>;

Setup and Root Components

Modern Gesture API

The recommended approach for creating sophisticated gesture interactions using the new Gesture API with GestureDetector and Gesture factory methods.

// Main component for detecting gestures
function GestureDetector(props: {
  gesture: ComposedGesture | GestureType;
  userSelect?: UserSelect;
  enableContextMenu?: boolean;
  touchAction?: TouchAction;
  children?: React.ReactNode;
}): JSX.Element;

// Factory object for creating gestures
interface GestureObjects {
  Tap(): TapGestureType;
  Pan(): PanGestureType;
  Pinch(): PinchGestureType;
  Rotation(): RotationGestureType;
  Fling(): FlingGestureType;
  LongPress(): LongPressGestureType;
  ForceTouch(): ForceTouchGestureType; // Deprecated
  Native(): NativeGestureType;
  Manual(): ManualGestureType;
  Hover(): HoverGestureType;
  Race(...gestures: GestureType[]): RaceGestureType;
  Simultaneous(...gestures: GestureType[]): SimultaneousGestureType;
  Exclusive(...gestures: GestureType[]): ExclusiveGestureType;
}

Modern Gesture API

Button Components

High-performance button components with native feedback and gesture support for creating interactive UI elements.

// Base button with gesture handling
function BaseButton(props: {
  onPress?: (pointerInside: boolean) => void;
  onLongPress?: () => void;
  onActiveStateChange?: (active: boolean) => void;
  delayLongPress?: number;
  children?: React.ReactNode;
}): JSX.Element;

// Rectangular button with underlay effect
function RectButton(props: BaseButtonProps & {
  underlayColor?: string;
  activeOpacity?: number;
}): JSX.Element;

// Borderless button with opacity effect
function BorderlessButton(props: BaseButtonProps & {
  activeOpacity?: number;
}): JSX.Element;

Button Components

Enhanced React Native Components

Drop-in replacements for standard React Native components with enhanced gesture support and performance optimizations.

// Enhanced ScrollView with gesture handler support
function ScrollView(props: ScrollViewProps): JSX.Element;

// Enhanced FlatList with gesture handler support
function FlatList<T>(props: FlatListProps<T>): JSX.Element;

// Enhanced touchable components
function TouchableOpacity(props: TouchableOpacityProps): JSX.Element;
function TouchableHighlight(props: TouchableHighlightProps): JSX.Element;
function TouchableWithoutFeedback(props: TouchableWithoutFeedbackProps): JSX.Element;

Enhanced Components

Advanced Layout Components

Sophisticated layout and interaction components for complex UI patterns like swipe-to-reveal and drawer layouts.

// Swipe-to-reveal component
function Swipeable(props: {
  friction?: number;
  leftThreshold?: number;
  rightThreshold?: number;
  renderLeftActions?: (
    progressAnimatedValue: Animated.AnimatedAddition,
    dragX: Animated.AnimatedAddition
  ) => React.ReactNode;
  renderRightActions?: (
    progressAnimatedValue: Animated.AnimatedAddition,
    dragX: Animated.AnimatedAddition
  ) => React.ReactNode;
  children: React.ReactNode;
}): JSX.Element;

// Modern pressable component
function Pressable(props: PressableProps & {
  simultaneousWithExternalGesture?: GestureRef[];
  requireExternalGestureToFail?: GestureRef[];
  blocksExternalGesture?: GestureRef[];
}): JSX.Element;

Advanced Layout Components

Gesture Event System

Comprehensive event types and payload structures for handling gesture interactions with detailed coordinate and timing information.

// Core event types
interface GestureEvent<T = Record<string, unknown>> {
  nativeEvent: T & {
    handlerTag: number;
    numberOfPointers: number;
    state: number;
  };
}

interface HandlerStateChangeEvent<T = Record<string, unknown>> {
  nativeEvent: T & {
    handlerTag: number;
    numberOfPointers: number;
    state: number;
    oldState: number;
  };
}

// New API event types
interface GestureUpdateEvent<T = Record<string, unknown>> {
  x: number;
  y: number;
  absoluteX: number;
  absoluteY: number;
  handlerTag: number;
  numberOfPointers: number;
  state: number;
} & T;

interface GestureStateChangeEvent<T = Record<string, unknown>> {
  x: number;
  y: number;
  absoluteX: number;
  absoluteY: number;
  handlerTag: number;
  numberOfPointers: number;
  state: number;
  oldState: number;
} & T;

Gesture Event System

Constants and Enums

Essential constants for gesture states, directions, pointer types, and mouse button handling across all gesture interactions.

// Gesture states
const State: {
  readonly UNDETERMINED: 0;
  readonly FAILED: 1;
  readonly BEGAN: 2;
  readonly CANCELLED: 3;
  readonly ACTIVE: 4;
  readonly END: 5;
};

// Direction constants
const Directions: {
  readonly RIGHT: 1;
  readonly LEFT: 2;
  readonly UP: 4;
  readonly DOWN: 8;
};

// Pointer input types
enum PointerType {
  TOUCH,
  STYLUS,
  MOUSE,
  KEY,
  OTHER,
}

// Mouse button constants
enum MouseButton {
  LEFT = 1,
  RIGHT = 2,
  MIDDLE = 4,
  BUTTON_4 = 8,
  BUTTON_5 = 16,
  ALL = 31,
}

Constants and Enums

Migration Guide

React Native Gesture Handler provides both legacy and modern APIs. The legacy gesture handler components (TapGestureHandler, PanGestureHandler, etc.) are deprecated in favor of the new Gesture API. While legacy components still work, new projects should use the modern GestureDetector and Gesture factory approach for better performance and composability.

Web Implementation

React Native Gesture Handler includes comprehensive web support with automatic platform-specific implementations. Web-specific configurations include:

  • userSelect - Controls text selection behavior
  • enableContextMenu - Enables/disables right-click context menu
  • touchAction - CSS touch-action property for web interactions