react-native-gesture-handler

Q: Como instalo o Gesture Handler no Expo SDK 57?

Adicione GestureHandlerRootView à raiz do layout. Certifique-se de que o plugin Babel do Reanimated seja o último.

Q: Posso anexar múltiplos gestos a uma view?

Sim - construa um gesto composto e passe-o para um único GestureDetector. Não aninhe múltiplos detectores na mesma view sem um plano de composição.

Q: FlatList deve vir do RNGH ou do react-native?

Comece com a FlatList do RN. Mude a lista horizontal interna para a FlatList do RNGH quando os gestos de scroll aninhados falharem no Android (Scrollables Aninhados).

Gesture Handler (RNGH) move o reconhecimento de toque para a camada nativa, de modo que pans, pinches e composições multi-toque permaneçam a 60fps. No Expo SDK 57, instale-o junto com Reanimated 4 e conduza valores animados a partir de callbacks de gestos na thread da UI.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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 },
});

Quando usar isso:

Linhas para excluir com swipe, cards arrastáveis, alças de puxar
Pinch-to-zoom em imagens e overlays de mapas
Bottom sheets e drawers que competem com scroll views
Qualquer gesto que precise permanecer suave enquanto as listas rolam

Exemplo de Trabalho

Pinch-to-zoom em uma imagem com pan simultâneo - gestos compostos em um 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%" },
});

// Limiar de swipe com runOnJS - dispensar quando o pan passar de -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);
    }
  });

Análise Detalhada

Gesture.Pan

Método	Propósito
`activeOffsetX/Y`	Exige movimento antes da ativação - evita roubar taps
`failOffsetY`	Falha o pan quando o movimento vertical domina - entrega de scroll
`minDistance`	Ignora micro-vibrações
`onUpdate`	Tradução por frame - mantenha apenas a matemática
`onEnd`	Snap, dispensar ou efeitos colaterais `runOnJS`

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

Use failOffsetY em linhas de swipe horizontal dentro de ScrollView vertical - veja Resolução de Conflitos de Gestos.

Gesture.Pinch

event.scale é relativo ao início do gesto - multiplique contra um valor compartilhado salvo em onEnd.
Limite a escala mínima/máxima para evitar imagens invertidas ou microscópicas.
Emparelhe com pan apenas quando scale > 1 para que imagens não ampliadas não se movam.

GestureDetector

Um GestureDetector envolve um objeto de gesto (simples ou composto).
O filho deve ser uma view nativa ou um componente Reanimated - não um fragmento com múltiplas raízes.
Para listas, envolva o conteúdo da linha, não a FlatList inteira.

Gestos Compostos

Compositor	Comportamento
`Gesture.Simultaneous(a, b)`	Ambos podem reconhecer juntos (pinch + pan)
`Gesture.Race(a, b)`	O primeiro vencedor assume o controle
`Gesture.Exclusive(a, b)`	O de maior prioridade vence quando ambos correspondem

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

RNGH ScrollView e FlatList

Importe scrollables de react-native-gesture-handler quando o scroll aninhado causar conflitos nativos:

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

Prefira isso no trilho interno primeiro - não em ambos os eixos cegamente (veja Scrollables Aninhados).

Armadilhas

Sem GestureHandlerRootView - Gestos nunca ativam; nenhum erro em tempo de compilação. Correção: Envolva a raiz de app/_layout.tsx.
setState em onUpdate - Descarta frames imediatamente. Correção: Valores compartilhados + useAnimatedStyle; runOnJS apenas no final.
Pan sem activeOffset - Linhas horizontais de swipe roubam o scroll vertical. Correção: activeOffsetX + ajuste de failOffsetY por layout.
Múltiplos GestureDetector aninhados - O pai pode consumir toques antes do filho. Correção: Compor com referências de scroll Simultaneous / Native em vez de empilhar detectores.
TouchableOpacity dentro de GestureDetector - Feedback duplo ou toques cancelados. Correção: Use Gesture.Tap() ou Pressable com planejamento de pointerEvents.
Plugin Reanimated ausente - onUpdate lança erros de worklet. Correção: react-native-reanimated/plugin por último na configuração do Babel.
Testando no Expo Go após upgrade nativo - O cliente de desenvolvimento antigo não possui os bits nativos do RNGH. Correção: Reconstrua o cliente de desenvolvimento ou use o Expo Go atual correspondente ao SDK 57.

Alternativas

Alternativa	Use Quando	Não Use Quando
`Pressable`	Botões, taps simples de linha de lista	Drag, swipe, multi-toque
PanResponder (RN core)	Manutenção legada	Novo código de gesto no SDK 57
`react-native-gesture-handler`	Pans/pinches de produção	UI estática não interativa
Apenas gestos nativos da plataforma	Telas totalmente nativas em brownfield	Biblioteca de componentes RN compartilhada
`@gorhom/bottom-sheet`	Física padrão de sheet	Modal simples sem drag

FAQs

Como instalo o Gesture Handler no Expo SDK 57?

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

Adicione GestureHandlerRootView à raiz do layout. Certifique-se de que o plugin Babel do Reanimated seja o último.

Por que usar Gesture.Pan em vez de PanResponder?

RNGH reconhece na thread nativa com melhor entrega de scroll.
A API compõe-se de forma limpa (Simultaneous, Race) e integra-se com worklets do Reanimated.

Para que serve o activeOffsetX?

O dedo deve se mover horizontalmente N pixels antes que o pan ative. Isso permite que o scroll vertical vença quando o usuário rola uma lista contendo linhas deslizáveis.

Posso anexar múltiplos gestos a uma view?

Sim - construa um gesto composto e passe-o para um único GestureDetector. Não aninhe múltiplos detectores na mesma view sem um plano de composição.

FlatList deve vir do RNGH ou do react-native?

Comece com a FlatList do RN. Mude a lista horizontal interna para a FlatList do RNGH quando os gestos de scroll aninhados falharem no Android (Scrollables Aninhados).

Como os gestos interagem com as stacks do Expo Router?

O swipe-back da stack é um gesto nativo. Pans de tela cheia personalizados podem precisar de gestureEnabled: false na tela ou simultaneousWithExternalGesture cuidadoso - veja Resolução de Conflitos de Gestos.

Preciso de react-native-reanimated para gestos?

Não estritamente para reconhecimento, mas toda atualização de UI de alta frequência deve usar valores compartilhados do Reanimated. setState por frame de pan causará travamentos.

Relacionados

Conceitos Básicos de Animações - quando passar de Pressable para RNGH
react-native-reanimated 4 - valores compartilhados impulsionados por gestos
Resolução de Conflitos de Gestos - ScrollView vs linhas de swipe vs sheets
Animações de Layout - movimento quando linhas montam/desmontam após swipe
Scrollables Aninhados - trilhos horizontais em feeds verticais
Melhores Práticas de Animações - checklist de envio para telas com muitos gestos

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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 },
});

Quando usar isso:

Linhas para excluir com swipe, cards arrastáveis, alças de puxar
Pinch-to-zoom em imagens e overlays de mapas
Bottom sheets e drawers que competem com scroll views
Qualquer gesto que precise permanecer suave enquanto as listas rolam

Exemplo de Trabalho

Pinch-to-zoom em uma imagem com pan simultâneo - gestos compostos em um 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%" },
});

// Limiar de swipe com runOnJS - dispensar quando o pan passar de -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);
    }
  });

Análise Detalhada

Gesture.Pan

Método	Propósito
`activeOffsetX/Y`	Exige movimento antes da ativação - evita roubar taps
`failOffsetY`	Falha o pan quando o movimento vertical domina - entrega de scroll
`minDistance`	Ignora micro-vibrações
`onUpdate`	Tradução por frame - mantenha apenas a matemática
`onEnd`	Snap, dispensar ou efeitos colaterais `runOnJS`

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

Use failOffsetY em linhas de swipe horizontal dentro de ScrollView vertical - veja Resolução de Conflitos de Gestos.

Gesture.Pinch

event.scale é relativo ao início do gesto - multiplique contra um valor compartilhado salvo em onEnd.
Limite a escala mínima/máxima para evitar imagens invertidas ou microscópicas.
Emparelhe com pan apenas quando scale > 1 para que imagens não ampliadas não se movam.

GestureDetector

Um GestureDetector envolve um objeto de gesto (simples ou composto).
O filho deve ser uma view nativa ou um componente Reanimated - não um fragmento com múltiplas raízes.
Para listas, envolva o conteúdo da linha, não a FlatList inteira.

Gestos Compostos

Compositor	Comportamento
`Gesture.Simultaneous(a, b)`	Ambos podem reconhecer juntos (pinch + pan)
`Gesture.Race(a, b)`	O primeiro vencedor assume o controle
`Gesture.Exclusive(a, b)`	O de maior prioridade vence quando ambos correspondem

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

RNGH ScrollView e FlatList

Importe scrollables de react-native-gesture-handler quando o scroll aninhado causar conflitos nativos:

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

Prefira isso no trilho interno primeiro - não em ambos os eixos cegamente (veja Scrollables Aninhados).

Armadilhas

Sem GestureHandlerRootView - Gestos nunca ativam; nenhum erro em tempo de compilação. Correção: Envolva a raiz de app/_layout.tsx.
setState em onUpdate - Descarta frames imediatamente. Correção: Valores compartilhados + useAnimatedStyle; runOnJS apenas no final.
Pan sem activeOffset - Linhas horizontais de swipe roubam o scroll vertical. Correção: activeOffsetX + ajuste de failOffsetY por layout.
Múltiplos GestureDetector aninhados - O pai pode consumir toques antes do filho. Correção: Compor com referências de scroll Simultaneous / Native em vez de empilhar detectores.
TouchableOpacity dentro de GestureDetector - Feedback duplo ou toques cancelados. Correção: Use Gesture.Tap() ou Pressable com planejamento de pointerEvents.
Plugin Reanimated ausente - onUpdate lança erros de worklet. Correção: react-native-reanimated/plugin por último na configuração do Babel.
Testando no Expo Go após upgrade nativo - O cliente de desenvolvimento antigo não possui os bits nativos do RNGH. Correção: Reconstrua o cliente de desenvolvimento ou use o Expo Go atual correspondente ao SDK 57.

Alternativas

Alternativa	Use Quando	Não Use Quando
`Pressable`	Botões, taps simples de linha de lista	Drag, swipe, multi-toque
PanResponder (RN core)	Manutenção legada	Novo código de gesto no SDK 57
`react-native-gesture-handler`	Pans/pinches de produção	UI estática não interativa
Apenas gestos nativos da plataforma	Telas totalmente nativas em brownfield	Biblioteca de componentes RN compartilhada
`@gorhom/bottom-sheet`	Física padrão de sheet	Modal simples sem drag

FAQs

Como instalo o Gesture Handler no Expo SDK 57?

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

Adicione GestureHandlerRootView à raiz do layout. Certifique-se de que o plugin Babel do Reanimated seja o último.

Por que usar Gesture.Pan em vez de PanResponder?

RNGH reconhece na thread nativa com melhor entrega de scroll.
A API compõe-se de forma limpa (Simultaneous, Race) e integra-se com worklets do Reanimated.

Para que serve o activeOffsetX?

O dedo deve se mover horizontalmente N pixels antes que o pan ative. Isso permite que o scroll vertical vença quando o usuário rola uma lista contendo linhas deslizáveis.

Posso anexar múltiplos gestos a uma view?

Sim - construa um gesto composto e passe-o para um único GestureDetector. Não aninhe múltiplos detectores na mesma view sem um plano de composição.

FlatList deve vir do RNGH ou do react-native?

Comece com a FlatList do RN. Mude a lista horizontal interna para a FlatList do RNGH quando os gestos de scroll aninhados falharem no Android (Scrollables Aninhados).

Como os gestos interagem com as stacks do Expo Router?

Preciso de react-native-reanimated para gestos?

Não estritamente para reconhecimento, mas toda atualização de UI de alta frequência deve usar valores compartilhados do Reanimated. setState por frame de pan causará travamentos.

Relacionados

Conceitos Básicos de Animações - quando passar de Pressable para RNGH
react-native-reanimated 4 - valores compartilhados impulsionados por gestos
Resolução de Conflitos de Gestos - ScrollView vs linhas de swipe vs sheets
Animações de Layout - movimento quando linhas montam/desmontam após swipe
Scrollables Aninhados - trilhos horizontais em feeds verticais
Melhores Práticas de Animações - checklist de envio para telas com muitos gestos

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

react-native-gesture-handler

Buscar na documentação

react-native-gesture-handler