react-native-gesture-handler

Q: ¿Cómo instalo Gesture Handler en Expo SDK 57?

Agrega GestureHandlerRootView al layout raíz. Asegúrate de que el plugin de Babel de Reanimated sea el último.

Q: ¿Puedo adjuntar múltiples gestos a una vista?

Sí - construye un gesto compuesto y pásalo a un único GestureDetector. No anides múltiples detectores en la misma vista sin un plan de composición.

Q: ¿Debe FlatList venir de RNGH o react-native?

Comienza con RN FlatList. Cambia la lista horizontal interna a RNGH FlatList cuando los gestos de scroll anidados fallan en Android (Desplazables Anidados).

Gesture Handler (RNGH) mueve el reconocimiento táctil a la capa nativa para que los pans, pinches y composiciones multi-toque se mantengan a 60fps. En Expo SDK 57, instálalo junto a Reanimated 4 e impulsa valores animados desde callbacks de gestos en el hilo de UI.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

npx expo install react-native-gesture-handler react-native-reanimated

// app/_layout.tsx
import { Stack } from "expo-router";
import { GestureHandlerRootView } from "react-native-gesture-handler";
 
export default function RootLayout() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <Stack />
    </GestureHandlerRootView>
  );
}

import { StyleSheet } from "react-native";
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import Animated, {
  useAnimatedStyle,
  useSharedValue,
  withSpring,
} from "react-native-reanimated";
 
export function SwipeableTile() {
  const translateX = useSharedValue(0);
 
  const pan = Gesture.Pan()
    .activeOffsetX([-12, 12])
    .onUpdate((e) => {
      translateX.value = e.translationX;
    })
    .onEnd(() => {
      translateX.value = withSpring(0);
    });
 
  const style = useAnimatedStyle(() => ({
    transform: [{ translateX: translateX.value }],
  }));
 
  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[styles.tile, style]} />
    </GestureDetector>
  );
}
 
const styles = StyleSheet.create({
  tile: { height: 72, backgroundColor: "#e2e8f0", borderRadius: 12 },
});

Cuándo usarlo:

Filas de deslizar para eliminar, tarjetas arrastrables, asas de arrastre
Pinch-to-zoom en imágenes y superposiciones de mapas
Bottom sheets y drawers que compiten con scroll views
Cualquier gesto que deba mantenerse suave mientras se desplaza la lista

Ejemplo funcional

Pinch-to-zoom en una imagen con pan simultáneo - gestos compuestos en un detector.

// components/zoomable-image.tsx
import { Image, StyleSheet, useWindowDimensions } from "react-native";
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import Animated, {
  useAnimatedStyle,
  useSharedValue,
  withTiming,
} from "react-native-reanimated";
 
type Props = { uri: string };
 
export function ZoomableImage({ uri }: Props) {
  const { width } = useWindowDimensions();
  const scale = useSharedValue(1);
  const savedScale = useSharedValue(1);
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);
  const savedX = useSharedValue(0);
  const savedY = useSharedValue(0);
 
  const pinch = Gesture.Pinch()
    .onUpdate((e) => {
      scale.value = savedScale.value * e.scale;
    })
    .onEnd(() => {
      if (scale.value < 1) {
        scale.value = withTiming(1);
        translateX.value = withTiming(0);
        translateY.value = withTiming(0);
        savedScale.value = 1;
        savedX.value = 0;
        savedY.value = 0;
      } else {
        savedScale.value = scale.value;
      }
    });
 
  const pan = Gesture.Pan()
    .minPointers(1)
    .maxPointers(2)
    .onUpdate((e) => {
      if (scale.value > 1) {
        translateX.value = savedX.value + e.translationX;
        translateY.value = savedY.value + e.translationY;
      }
    })
    .onEnd(() => {
      savedX.value = translateX.value;
      savedY.value = translateY.value;
    });
 
  const doubleTap = Gesture.Tap()
    .numberOfTaps(2)
    .onEnd(() => {
      if (scale.value > 1) {
        scale.value = withTiming(1);
        translateX.value = withTiming(0);
        translateY.value = withTiming(0);
        savedScale.value = 1;
        savedX.value = 0;
        savedY.value = 0;
      } else {
        scale.value = withTiming(2);
        savedScale.value = 2;
      }
    });
 
  const composed = Gesture.Simultaneous(
    pinch,
    pan,
    Gesture.Exclusive(doubleTap, Gesture.Tap())
  );
 
  const style = useAnimatedStyle(() => ({
    transform: [
      { translateX: translateX.value },
      { translateY: translateY.value },
      { scale: scale.value },
    ],
  }));
 
  return (
    <GestureDetector gesture={composed}>
      <Animated.View style={{ width, height: width * 0.75 }}>
        <Animated.Image
          source={{ uri }}
          style={[styles.image, style]}
          resizeMode="cover"
        />
      </Animated.View>
    </GestureDetector>
  );
}
 
const styles = StyleSheet.create({
  image: { width: "100%", height: "100%" },
});

// Umbral de deslizamiento con runOnJS - descartar cuando pan pasa -120px
import { runOnJS } from "react-native-reanimated";
 
const pan = Gesture.Pan()
  .onUpdate((e) => {
    translateX.value = Math.min(0, e.translationX);
  })
  .onEnd((e) => {
    if (e.translationX < -120) {
      runOnJS(onArchive)();
    } else {
      translateX.value = withSpring(0);
    }
  });

Inmersión profunda

Gesture.Pan

Método	Propósito
`activeOffsetX/Y`	Requiere movimiento antes de la activación - evita el robo de taps
`failOffsetY`	Falla pan cuando el movimiento vertical domina - entrega de scroll
`minDistance`	Ignorar micro-jitter
`onUpdate`	Traducción por fotograma - mantén solo las matemáticas
`onEnd`	Ajusta, descarta, o efectos secundarios con `runOnJS`

Gesture.Pan()
  .activeOffsetX([-10, 10])
  .failOffsetY([-15, 15])

Usa failOffsetY en filas de deslizamiento horizontal dentro de ScrollView vertical - ver Resolución de Conflictos de Gestos.

Gesture.Pinch

event.scale es relativo al inicio del gesto - multiplica contra un valor compartido guardado en onEnd.
Fija escala mín/máx para evitar imágenes invertidas o microscópicas.
Empareja con pan solo cuando scale > 1 para que las imágenes sin zoom no se desvíen.

GestureDetector

Un GestureDetector envuelve un objeto gesto (simple o compuesto).
El hijo debe ser una vista nativa o componente Reanimated - no un fragmento con múltiples raíces.
Para listas, envuelve el contenido de la fila, no el FlatList completo.

Gestos compuestos

Compositor	Comportamiento
`Gesture.Simultaneous(a, b)`	Ambos pueden reconocerse juntos (pinch + pan)
`Gesture.Race(a, b)`	El primer ganador se apodera
`Gesture.Exclusive(a, b)`	Mayor prioridad gana cuando ambos coinciden

const drag = Gesture.Pan();
const longPress = Gesture.LongPress().minDuration(400);
const rowGesture = Gesture.Race(longPress, drag);

RNGH ScrollView y FlatList

Importa desplazables desde react-native-gesture-handler cuando el desplazamiento anidado causa conflictos nativos:

import { ScrollView } from "react-native-gesture-handler";

Prefiere esto en el rail interno primero - no ambos ejes ciegamente (ver Desplazables Anidados).

Errores comunes

Sin GestureHandlerRootView - Los gestos nunca se activan; sin error en tiempo de compilación. Solución: Envuelve la raíz de app/_layout.tsx.
setState en onUpdate - Cae fotogramas inmediatamente. Solución: Valores compartidos + useAnimatedStyle; runOnJS solo al final.
Pan sin activeOffset - Los pans de filas horizontales roban scroll vertical. Solución: Sintonización de activeOffsetX + failOffsetY por layout.
Múltiples GestureDetectors anidados - El padre puede consumir toques antes del hijo. Solución: Componer con Simultaneous / referencias de scroll Native en lugar de apilar detectores.
TouchableOpacity dentro de GestureDetector - Retroalimentación doble o presiones canceladas. Solución: Usa Gesture.Tap() o Pressable con planificación de pointerEvents.
Plugin Reanimated faltante - onUpdate lanza errores de worklet. Solución: react-native-reanimated/plugin último en config de Babel.
Pruebas en Expo Go después de actualización nativa - El cliente dev antiguo carece de bits nativos de RNGH. Solución: Reconstruye cliente dev o usa Expo Go actual que coincida con SDK 57.

Alternativas

Alternativa	Úsalo cuando	No lo uses cuando
`Pressable`	Botones, taps simples en filas	Arrastre, deslizamiento, multi-toque
PanResponder (núcleo RN)	Mantenimiento heredado	Nuevo código de gestos en SDK 57
`react-native-gesture-handler`	Producciones pans/pinches	UI estática no interactiva
Gestos nativos solo de plataforma	Pantallas completamente nativas en brownfield	Biblioteca de componentes RN compartida
`@gorhom/bottom-sheet`	Física de sheet estándar	Modal simple sin arrastre

FAQs

¿Cómo instalo Gesture Handler en Expo SDK 57?

npx expo install react-native-gesture-handler react-native-reanimated

Agrega GestureHandlerRootView al layout raíz. Asegúrate de que el plugin de Babel de Reanimated sea el último.

¿Por qué usar Gesture.Pan en lugar de PanResponder?

RNGH reconoce en el hilo nativo con mejor entrega de scroll.
API se compone limpiamente (Simultaneous, Race) e se integra con worklets de Reanimated.

¿Para qué sirve activeOffsetX?

El dedo debe moverse horizontalmente N píxeles antes de que se active el pan. Esto permite que el scroll vertical gane cuando el usuario desplaza una lista que contiene filas deslizables.

¿Puedo adjuntar múltiples gestos a una vista?

Sí - construye un gesto compuesto y pásalo a un único GestureDetector. No anides múltiples detectores en la misma vista sin un plan de composición.

¿Debe FlatList venir de RNGH o react-native?

Comienza con RN FlatList. Cambia la lista horizontal interna a RNGH FlatList cuando los gestos de scroll anidados fallan en Android (Desplazables Anidados).

¿Cómo interactúan los gestos con stacks de Expo Router?

El swipe-back de stack es un gesto nativo. Los pans personalizados de pantalla completa pueden necesitar gestureEnabled: false en la pantalla o cuidadoso simultaneousWithExternalGesture - ver Resolución de Conflictos de Gestos.

¿Necesito react-native-reanimated para gestos?

No estrictamente para reconocimiento, pero cada actualización de UI de alta frecuencia debe usar valores compartidos de Reanimated. setState por fotograma de pan janqueará.

Relacionado

Conceptos básicos de animaciones - cuándo pasar de Pressable a RNGH
react-native-reanimated 4 - valores compartidos impulsados por gestos
Resolución de Conflictos de Gestos - ScrollView vs filas de deslizamiento vs sheets
Animaciones de layout - movimiento cuando filas se montan/desmontan después del deslizamiento
Desplazables Anidados - rails horizontales en feeds verticales
Mejores prácticas de animaciones - checklist de envío para pantallas pesadas en gestos

Versiones de Stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0, y Expo SDK 57 (expo ~57.0.4).

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

npx expo install react-native-gesture-handler react-native-reanimated

// app/_layout.tsx
import { Stack } from "expo-router";
import { GestureHandlerRootView } from "react-native-gesture-handler";
 
export default function RootLayout() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <Stack />
    </GestureHandlerRootView>
  );
}

import { StyleSheet } from "react-native";
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import Animated, {
  useAnimatedStyle,
  useSharedValue,
  withSpring,
} from "react-native-reanimated";
 
export function SwipeableTile() {
  const translateX = useSharedValue(0);
 
  const pan = Gesture.Pan()
    .activeOffsetX([-12, 12])
    .onUpdate((e) => {
      translateX.value = e.translationX;
    })
    .onEnd(() => {
      translateX.value = withSpring(0);
    });
 
  const style = useAnimatedStyle(() => ({
    transform: [{ translateX: translateX.value }],
  }));
 
  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[styles.tile, style]} />
    </GestureDetector>
  );
}
 
const styles = StyleSheet.create({
  tile: { height: 72, backgroundColor: "#e2e8f0", borderRadius: 12 },
});

Cuándo usarlo:

Filas de deslizar para eliminar, tarjetas arrastrables, asas de arrastre
Pinch-to-zoom en imágenes y superposiciones de mapas
Bottom sheets y drawers que compiten con scroll views
Cualquier gesto que deba mantenerse suave mientras se desplaza la lista

Ejemplo funcional

Pinch-to-zoom en una imagen con pan simultáneo - gestos compuestos en un detector.

// components/zoomable-image.tsx
import { Image, StyleSheet, useWindowDimensions } from "react-native";
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import Animated, {
  useAnimatedStyle,
  useSharedValue,
  withTiming,
} from "react-native-reanimated";
 
type Props = { uri: string };
 
export function ZoomableImage({ uri }: Props) {
  const { width } = useWindowDimensions();
  const scale = useSharedValue(1);
  const savedScale = useSharedValue(1);
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);
  const savedX = useSharedValue(0);
  const savedY = useSharedValue(0);
 
  const pinch = Gesture.Pinch()
    .onUpdate((e) => {
      scale.value = savedScale.value * e.scale;
    })
    .onEnd(() => {
      if (scale.value < 1) {
        scale.value = withTiming(1);
        translateX.value = withTiming(0);
        translateY.value = withTiming(0);
        savedScale.value = 1;
        savedX.value = 0;
        savedY.value = 0;
      } else {
        savedScale.value = scale.value;
      }
    });
 
  const pan = Gesture.Pan()
    .minPointers(1)
    .maxPointers(2)
    .onUpdate((e) => {
      if (scale.value > 1) {
        translateX.value = savedX.value + e.translationX;
        translateY.value = savedY.value + e.translationY;
      }
    })
    .onEnd(() => {
      savedX.value = translateX.value;
      savedY.value = translateY.value;
    });
 
  const doubleTap = Gesture.Tap()
    .numberOfTaps(2)
    .onEnd(() => {
      if (scale.value > 1) {
        scale.value = withTiming(1);
        translateX.value = withTiming(0);
        translateY.value = withTiming(0);
        savedScale.value = 1;
        savedX.value = 0;
        savedY.value = 0;
      } else {
        scale.value = withTiming(2);
        savedScale.value = 2;
      }
    });
 
  const composed = Gesture.Simultaneous(
    pinch,
    pan,
    Gesture.Exclusive(doubleTap, Gesture.Tap())
  );
 
  const style = useAnimatedStyle(() => ({
    transform: [
      { translateX: translateX.value },
      { translateY: translateY.value },
      { scale: scale.value },
    ],
  }));
 
  return (
    <GestureDetector gesture={composed}>
      <Animated.View style={{ width, height: width * 0.75 }}>
        <Animated.Image
          source={{ uri }}
          style={[styles.image, style]}
          resizeMode="cover"
        />
      </Animated.View>
    </GestureDetector>
  );
}
 
const styles = StyleSheet.create({
  image: { width: "100%", height: "100%" },
});

// Umbral de deslizamiento con runOnJS - descartar cuando pan pasa -120px
import { runOnJS } from "react-native-reanimated";
 
const pan = Gesture.Pan()
  .onUpdate((e) => {
    translateX.value = Math.min(0, e.translationX);
  })
  .onEnd((e) => {
    if (e.translationX < -120) {
      runOnJS(onArchive)();
    } else {
      translateX.value = withSpring(0);
    }
  });

Inmersión profunda

Gesture.Pan

Método	Propósito
`activeOffsetX/Y`	Requiere movimiento antes de la activación - evita el robo de taps
`failOffsetY`	Falla pan cuando el movimiento vertical domina - entrega de scroll
`minDistance`	Ignorar micro-jitter
`onUpdate`	Traducción por fotograma - mantén solo las matemáticas
`onEnd`	Ajusta, descarta, o efectos secundarios con `runOnJS`

Gesture.Pan()
  .activeOffsetX([-10, 10])
  .failOffsetY([-15, 15])

Usa failOffsetY en filas de deslizamiento horizontal dentro de ScrollView vertical - ver Resolución de Conflictos de Gestos.

Gesture.Pinch

event.scale es relativo al inicio del gesto - multiplica contra un valor compartido guardado en onEnd.
Fija escala mín/máx para evitar imágenes invertidas o microscópicas.
Empareja con pan solo cuando scale > 1 para que las imágenes sin zoom no se desvíen.

GestureDetector

Un GestureDetector envuelve un objeto gesto (simple o compuesto).
El hijo debe ser una vista nativa o componente Reanimated - no un fragmento con múltiples raíces.
Para listas, envuelve el contenido de la fila, no el FlatList completo.

Gestos compuestos

Compositor	Comportamiento
`Gesture.Simultaneous(a, b)`	Ambos pueden reconocerse juntos (pinch + pan)
`Gesture.Race(a, b)`	El primer ganador se apodera
`Gesture.Exclusive(a, b)`	Mayor prioridad gana cuando ambos coinciden

const drag = Gesture.Pan();
const longPress = Gesture.LongPress().minDuration(400);
const rowGesture = Gesture.Race(longPress, drag);

RNGH ScrollView y FlatList

Importa desplazables desde react-native-gesture-handler cuando el desplazamiento anidado causa conflictos nativos:

import { ScrollView } from "react-native-gesture-handler";

Prefiere esto en el rail interno primero - no ambos ejes ciegamente (ver Desplazables Anidados).

Errores comunes

Sin GestureHandlerRootView - Los gestos nunca se activan; sin error en tiempo de compilación. Solución: Envuelve la raíz de app/_layout.tsx.
setState en onUpdate - Cae fotogramas inmediatamente. Solución: Valores compartidos + useAnimatedStyle; runOnJS solo al final.
Pan sin activeOffset - Los pans de filas horizontales roban scroll vertical. Solución: Sintonización de activeOffsetX + failOffsetY por layout.
Múltiples GestureDetectors anidados - El padre puede consumir toques antes del hijo. Solución: Componer con Simultaneous / referencias de scroll Native en lugar de apilar detectores.
TouchableOpacity dentro de GestureDetector - Retroalimentación doble o presiones canceladas. Solución: Usa Gesture.Tap() o Pressable con planificación de pointerEvents.
Plugin Reanimated faltante - onUpdate lanza errores de worklet. Solución: react-native-reanimated/plugin último en config de Babel.
Pruebas en Expo Go después de actualización nativa - El cliente dev antiguo carece de bits nativos de RNGH. Solución: Reconstruye cliente dev o usa Expo Go actual que coincida con SDK 57.

Alternativas

Alternativa	Úsalo cuando	No lo uses cuando
`Pressable`	Botones, taps simples en filas	Arrastre, deslizamiento, multi-toque
PanResponder (núcleo RN)	Mantenimiento heredado	Nuevo código de gestos en SDK 57
`react-native-gesture-handler`	Producciones pans/pinches	UI estática no interactiva
Gestos nativos solo de plataforma	Pantallas completamente nativas en brownfield	Biblioteca de componentes RN compartida
`@gorhom/bottom-sheet`	Física de sheet estándar	Modal simple sin arrastre

FAQs

¿Cómo instalo Gesture Handler en Expo SDK 57?

npx expo install react-native-gesture-handler react-native-reanimated

Agrega GestureHandlerRootView al layout raíz. Asegúrate de que el plugin de Babel de Reanimated sea el último.

¿Por qué usar Gesture.Pan en lugar de PanResponder?

RNGH reconoce en el hilo nativo con mejor entrega de scroll.
API se compone limpiamente (Simultaneous, Race) e se integra con worklets de Reanimated.

¿Para qué sirve activeOffsetX?

El dedo debe moverse horizontalmente N píxeles antes de que se active el pan. Esto permite que el scroll vertical gane cuando el usuario desplaza una lista que contiene filas deslizables.

¿Puedo adjuntar múltiples gestos a una vista?

Sí - construye un gesto compuesto y pásalo a un único GestureDetector. No anides múltiples detectores en la misma vista sin un plan de composición.

¿Debe FlatList venir de RNGH o react-native?

Comienza con RN FlatList. Cambia la lista horizontal interna a RNGH FlatList cuando los gestos de scroll anidados fallan en Android (Desplazables Anidados).

¿Cómo interactúan los gestos con stacks de Expo Router?

¿Necesito react-native-reanimated para gestos?

No estrictamente para reconocimiento, pero cada actualización de UI de alta frecuencia debe usar valores compartidos de Reanimated. setState por fotograma de pan janqueará.

Relacionado

Conceptos básicos de animaciones - cuándo pasar de Pressable a RNGH
react-native-reanimated 4 - valores compartidos impulsados por gestos
Resolución de Conflictos de Gestos - ScrollView vs filas de deslizamiento vs sheets
Animaciones de layout - movimiento cuando filas se montan/desmontan después del deslizamiento
Desplazables Anidados - rails horizontales en feeds verticales
Mejores prácticas de animaciones - checklist de envío para pantallas pesadas en gestos

Versiones de Stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0, y Expo SDK 57 (expo ~57.0.4).

react-native-gesture-handler

Buscar en la documentación

react-native-gesture-handler