Stack Navigator: o que é, navegação por pilha em React Native

O que é Stack Navigator?

Stack Navigator — um dos navegadores básicos da biblioteca React Navigation que implementa o modelo de pilha de telas. Ele fornece a navegação familiar para usuários de dispositivos móveis: abrir uma nova tela é acompanhado por uma animação de deslizar para a direita, e o botão «Voltar» ou o gesto de deslizar retorna o usuário à tela anterior. O Stack Navigator é compatível com iOS e Android, usando componentes nativos da plataforma para máximo desempenho.

React Navigation é a biblioteca de navegação mais popular para React Native, instalada em 85% dos projetos (de acordo com dados do npm, 2026). O Stack Navigator faz parte do seu núcleo e está disponível em duas implementações: createNativeStackNavigator (nativa, recomendada) e createStackNavigator (JavaScript, para animações personalizadas complexas). A versão nativa apareceu no React Navigation v5 e se tornou o padrão no v6+.

A principal vantagem do Stack Navigator — o comportamento natural familiar aos usuários de iOS e Android. No iOS, a pilha é visualmente representada pelo UINavigationController, no Android — pelo FragmentManager com animação de deslizar. O desenvolvedor não precisa implementar a lógica da pilha manualmente — o navegador gerencia os estados das telas, a pilha de retorno e as animações automaticamente.

Como funciona a navegação por pilha

A navegação por pilha é baseada no princípio LIFO (Last In, First Out). Quando um usuário abre uma nova tela, o navegador a coloca no topo da pilha. Ao pressionar «Voltar», a tela superior é removida e o usuário vê a anterior. A pilha pode conter qualquer número de telas — o único limite é a memória do dispositivo.

Cada tela na pilha preserva seu estado. Ao retornar a uma tela anterior, seu estado é restaurado automaticamente. Isso diferencia a pilha de outros tipos de navegação (Tab, Drawer), onde as telas podem ser recriadas. O React Navigation gerencia o estado através de seu próprio mecanismo de contexto de navegação.

Gesto de deslizar para voltar

No iOS, o Stack Navigator suporta um gesto de deslizar da borda esquerda para voltar — este é o comportamento padrão do iOS que os usuários esperam. No Android, o gesto está desativado por padrão, mas pode ser ativado através da opção gestureEnabled. No Native Stack, o gesto funciona nativamente sem atrasos da thread JavaScript.

Native Stack vs JS Stack

O React Navigation oferece dois tipos de Stack Navigator: Native Stack (createNativeStackNavigator) e JS Stack (createStackNavigator). A principal diferença — onde a animação é executada. O Native Stack usa drivers de animação nativos do iOS e Android, enquanto o JS Stack funciona através da thread JavaScript do React Native. A escolha entre eles depende dos requisitos de desempenho e personalização.

Native Stack é recomendado para a maioria dos projetos. Ele fornece animações suaves a 60 FPS sem bloquear a thread JS, suporta o gesto de deslizar para voltar do sistema no iOS e usa transições nativas — slide no iOS, fade no Android. No entanto, o Native Stack é limitado na personalização de animações: apenas um conjunto predefinido de transições está disponível.

JS Stack dá controle total sobre as animações através do cardStyleInterpolator. O desenvolvedor pode criar qualquer animação: escala, rotação, paralaxe, curvas personalizadas. A desvantagem — as animações são executadas na thread JS, o que pode causar quedas de quadros em dispositivos fracos com transições complexas. Para 70% dos projetos, o Native Stack é mais que suficiente.

// Native Stack — implementação recomendada
import { createNativeStackNavigator } from '@react-navigation/native-stack';

type RootStackParamList = {
  Home: undefined;
  Profile: { userId: string; name: string };
  Settings: undefined;
};

const Stack = createNativeStackNavigator<RootStackParamList>();

function AppNavigator() {
  return (
    <Stack.Navigator screenOptions={{ headerShown: true }}>
      <Stack.Screen name="Home" component={HomeScreen} />
      <Stack.Screen name="Profile" component={ProfileScreen} />
      <Stack.Screen name="Settings" component={SettingsScreen} />
    </Stack.Navigator>
  );
}

Instalação e configuração do Stack Navigator

Para começar com o Stack Navigator, é necessário instalar o React Navigation e suas dependências. O conjunto mínimo inclui @react-navigation/native, @react-navigation/native-stack e react-native-screens. Após a instalação, o aplicativo é envolvido no NavigationContainer — um contexto que fornece o estado de navegação a todos os componentes filhos.

# Instalação das dependências do React Navigation
npm install @react-navigation/native @react-navigation/native-stack
npm install react-native-screens react-native-safe-area-context

# Para iOS — instalação do pod
cd ios && pod install && cd ..

Após a instalação, o Stack.Navigator é criado com telas específicas definidas no RootStackParamList. Cada tela é vinculada a um componente React através da prop component. O navegador pode ser raiz ou estar aninhado dentro de outro navegador (Tab, Drawer). Para configuração, são usados screenOptions — comuns para todas as telas ou individuais para cada uma.

import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';

type RootStackParamList = {
  Home: undefined;
  Details: { itemId: number; title: string };
};

const Stack = createNativeStackNavigator<RootStackParamList>();

export default function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator initialRouteName="Home"
        screenOptions={{
          headerStyle: { backgroundColor: '#6200ee' },
          headerTintColor: '#fff',
          gestureEnabled: true,
        }}>
        <Stack.Screen name="Home" component={HomeScreen}
          options={{ title: 'Início' }} />
        <Stack.Screen name="Details" component={DetailsScreen}
          options={({ route }) => ({ title: route.params.title })} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

Parâmetros e personalização do Stack Navigator

Stack Navigator fornece muitas opções para personalizar aparência e comportamento. Os principais parâmetros são definidos através de screenOptions no nível do Navigator ou options no nível da Screen. O desenvolvedor pode configurar o cabeçalho, a animação de transição, o gesto de deslizar, o estilo do cartão e o escurecimento do fundo. A flexibilidade das configurações permite adaptar a navegação ao sistema de design do aplicativo.

Animações personalizadas através do cardStyleInterpolator

Para JS Stack, cardStyleInterpolator permite criar animações de transição arbitrárias entre telas. É uma ferramenta poderosa para implementar efeitos visuais únicos: escala, rotação, paralaxe, giro horizontal. A função recebe os valores atuais do progresso da animação (current, next) e retorna estilos para os elementos que estão sendo animados.

Tipagem de navegação com TypeScript

Stack Navigator suporta tipagem completa via TypeScript. Para isso, define-se RootStackParamList — um tipo objeto onde as chaves são os nomes das telas e os valores são os tipos dos parâmetros. Após a tipagem, navigation.navigate e route.params obtêm autocompletar e verificação de tipos. Isso elimina erros de passagem de parâmetros em tempo de compilação.

type RootStackParamList = {
  Home: undefined;
  Product: { id: string; category: string };
  Checkout: { items: CartItem[]; total: number };
};

// Tela tipada
type ProductScreenProps = NativeStackScreenProps<RootStackParamList, 'Product'>;

function ProductScreen({ navigation, route }: ProductScreenProps) {
  const { id, category } = route.params;

  return (
    <View>
      <Text>Produto {id} — {category}</Text>
      <Button title="Adicionar ao carrinho"
        onPress={() => navigation.navigate('Checkout', {
          items: [{ id, quantity: 1 }],
          total: 99.99,
        })} />
    </View>
  );
}

Cenários avançados: janelas modais e grupos

Stack Navigator suporta agrupamento de telas e janelas modais. Os grupos (Screen Group) permitem aplicar configurações comuns a várias telas sem duplicação. As janelas modais são implementadas através de stack presentation: 'modal' — a tela abre de baixo com escurecimento do fundo, como um modal do sistema no iOS. Esta opção está disponível apenas no Native Stack.

Para navegação complexa, o Stack Navigator pode ser aninhado dentro de um Tab Navigator ou Drawer Navigator. Por exemplo, a aba «Início» tem sua própria pilha de telas, e a aba «Perfil» tem a sua. Essa composição de navegadores é a abordagem padrão para aplicações de produção. Cada pilha é isolada: a pilha de retorno dentro de uma aba não afeta outras abas.

// Pilha aninhada no Tab Navigator
const HomeStack = createNativeStackNavigator<HomeStackParamList>();

function HomeStackScreen() {
  return (
    <HomeStack.Navigator>
      <HomeStack.Screen name="Feed" component={FeedScreen} />
      <HomeStack.Screen name="PostDetail" component={PostDetailScreen}
        options={{ presentation: 'modal' }} />
    </HomeStack.Navigator>
  );
}

// Grupos de telas com opções compartilhadas
<Stack.Navigator>
  <Stack.Group screenOptions={{ headerShown: true }}>
    <Stack.Screen name="Main" component={MainScreen} />
    <Stack.Screen name="About" component={AboutScreen} />
  </Stack.Group>
  <Stack.Screen name="Auth" component={AuthScreen}
    options={{ presentation: 'modal', headerShown: false }} />
</Stack.Navigator>