Navegação em Pilha

Q: Como oculto o cabeçalho em uma tela?

Defina headerShown: false na tela específica - screenOptions pai ainda pode ser aplicado a irmãos.

Q: Como adiciono um botão direito no cabeçalho?

Use props de renderização headerLeft, headerRight ou headerTitle - mesma API do React Navigation.

Q: Posso usar um componente de cabeçalho personalizado?

Sim - header: () => nas opções da tela. Prefira cabeçalhos de sistema de design para consistência. Oculte o padrão com headerShown: false e renderize o seu próprio no corpo da tela apenas quando o cabeçalho da pilha for insuficiente.

Q: Como reinicio a pilha no logout?

replace remove rotas anteriores do histórico. Para reinícios complexos, remonte o navegador com uma key vinculada a userId no layout raiz.

Q: Modais devem ser rotas ou React Native Modal?

Rotas quando o modal tem uma URL, deep link ou deve aparecer no histórico de navegação. RN Modal para UI efêmera sem caminho compartilhável. Documente a escolha da equipe em um ADR quando ambos os padrões aparecerem.

Q: Como passo dados entre telas da pilha?

Parâmetros de URL para IDs e estado superficial (params: { id }) Armazenamento global (Zustand, TanStack Query) para entidades compartilhadas Evite JSON grande em parâmetros - URLs são registradas e persistidas no estado de navegação Veja Rotas Tipadas para tipagem de parâmetros.

Q: Posso aninhar uma pilha dentro de outra pilha?

Sim - app/settings/_layout.tsx pode exportar enquanto está dentro da pilha raiz. Limite a profundidade para duas pilhas (raiz + recurso) antes que a experiência do usuário e a depuração sofram.

Push/pop, cabeçalhos e opções de tela em diretórios app/. Stack do expo-router é a interface baseada em arquivos do @react-navigation/native-stack - cada arquivo de rota irmão sob uma pasta com _layout.tsx se torna uma tela de pilha.

Receita

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

npx expo install expo-router

app/
├── _layout.tsx           # Pilha raiz
├── index.tsx
├── settings.tsx
└── orders/
    ├── _layout.tsx       # Pilha aninhada para /orders/*
    ├── index.tsx
    └── [id].tsx

// app/_layout.tsx
import { Stack } from "expo-router";
 
export default function RootLayout() {
  return (
    <Stack
      screenOptions={{
        headerShown: true,
        animation: "slide_from_right",
      }}
    >
      <Stack.Screen name="index" options={{ title: "Início" }} />
      <Stack.Screen name="settings" options={{ title: "Configurações" }} />
    </Stack>
  );
}

// app/orders/_layout.tsx
import { Stack } from "expo-router";
 
export default function OrdersLayout() {
  return (
    <Stack>
      <Stack.Screen name="index" options={{ title: "Pedidos" }} />
      <Stack.Screen name="[id]" options={{ title: "Pedido" }} />
    </Stack>
  );
}

Quando usar isso:

Fluxos lineares de detalhamento (lista → detalhe → editar)
Modais de tela inteira via presentation: "modal"
Ocultar cabeçalhos em telas de splash/autenticação com headerShown: false
Pilhas aninhadas dentro de abas quando uma aba precisa de seu próprio histórico de push

Exemplo de Trabalho

Uma pilha raiz com um splash de cabeçalho oculto, uma tela de configurações com um título dinâmico e uma pilha de pedidos aninhada.

// app/_layout.tsx
import { Stack } from "expo-router";
import { ThemeProvider } from "@/shared/theme";
 
export default function RootLayout() {
  return (
    <ThemeProvider>
      <Stack>
        <Stack.Screen name="index" options={{ headerShown: false }} />
        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
        <Stack.Screen
          name="settings"
          options={{
            title: "Configurações",
            presentation: "card",
          }}
        />
      </Stack>
    </ThemeProvider>
  );
}

// app/settings.tsx
import { useNavigation } from "expo-router";
import { useEffect } from "react";
import { ActivityIndicator, Text, View } from "react-native";
 
export default function SettingsScreen() {
  const navigation = useNavigation();
 
  useEffect(() => {
    navigation.setOptions({ title: "Configurações da Conta" });
  }, [navigation]);
 
  return (
    <View style={{ flex: 1, padding: 16 }}>
      <Text>Conteúdo das configurações</Text>
    </View>
  );
}

// app/orders/[id].tsx
import { useLocalSearchParams, Stack } from "expo-router";
import { useEffect, useState } from "react";
import { ActivityIndicator, Text, View } from "react-native";
 
export default function OrderDetailScreen() {
  const { id } = useLocalSearchParams<{ id: string }>();
  const [title, setTitle] = useState(`Pedido #${id}`);
 
  useEffect(() => {
    // Simula busca - então atualiza o cabeçalho via filho do layout
    const timer = setTimeout(() => setTitle(`Pedido ${id} - Enviado`), 400);
    return () => clearTimeout(timer);
  }, [id]);
 
  return (
    <>
      <Stack.Screen options={{ title }} />
      <View style={{ flex: 1, padding: 16 }}>
        <Text>Detalhe do pedido {id}</Text>
      </View>
    </>
  );
}

// Navega entre telas da pilha
import { Link, router } from "expo-router";
import { Pressable, Text, View } from "react-native";
 
export function HomeActions() {
  return (
    <View style={{ gap: 12 }}>
      <Link href="/settings">Configurações (declarativo)</Link>
      <Pressable onPress={() => router.push("/orders/42")}>
        <Text>Pedido 42 (imperativo)</Text>
      </Pressable>
    </View>
  );
}

Mergulho Profundo

Como o sistema de arquivos se torna uma pilha

app/orders/_layout.tsx  →  <Stack> envolve esta pasta
app/orders/index.tsx    →  rota inicial (fundo da pilha)
app/orders/[id].tsx     →  empurrado ao navegar para /orders/:id
app/orders/new.tsx      →  empurrado ao navegar para /orders/new

Expo Router registra automaticamente cada arquivo de rota como um Stack.Screen - <Stack.Screen name="..."> explícito é opcional, mas recomendado para opções
A rota inicial é a primeira tela correspondente na navegação; deep links podem abrir [id] diretamente
Arquivos irmãos compartilham um histórico de pilha - pastas sem _layout.tsx herdam o navegador pai

Camadas de configuração do cabeçalho

Camada	API	Precedência
Padrão do Navegador	`screenOptions` em `<Stack>`	Mais baixa
Filho do Layout	`<Stack.Screen options={...}>`	Média
Arquivo de Rota	`export const options = {...}`	Média
Tempo de Execução	`navigation.setOptions()` ou `<Stack.Screen options>` no render	Mais alta

// Opções estáticas por rota (co-localizadas)
export const options = {
  title: "Perfil",
  headerBackTitle: "Voltar",
};

Modos de apresentação

<Stack.Screen
  name="compose"
  options={{
    presentation: "modal",        // Modal de cartão iOS; tela inteira Android
    gestureEnabled: true,
    headerShown: true,
  }}
/>

card (padrão) - animação de push padrão
modal - apresentação de modal; emparelhe com um grupo de rotas (modals) para organização
transparentModal - sobrepõe a tela anterior (use com moderação - acessibilidade e o back do Android diferem)
fullScreenModal - modal de ponta a ponta no iOS

Aninhando pilhas sob abas

(tabs)/_layout.tsx     → Abas (barra de abas sempre visível)
(tabs)/orders/_layout  → Pilha (push apenas dentro da aba Pedidos)

Cada aba mantém um histórico de pilha independente - alternar abas preserva o estado da pilha de cada aba por padrão. Reinicie as pilhas ao sair com router.replace ou remontando a chave do navegador.

Armadilhas

_layout.tsx ausente em uma pasta com várias telas - irmãos podem se achatar inesperadamente na pilha pai. Correção: Adicione orders/_layout.tsx com <Stack /> quando uma pasta tiver index + [id].
Nomes de tela duplicados de arquivos index - orders.tsx e orders/index.tsx entram em conflito. Correção: Escolha uma forma de URL por recurso.
headerShown: false na pilha raiz, mas esperando cabeçalhos aninhados - pilhas filhas devem definir headerShown: true explicitamente. Correção: Configure cabeçalhos no _layout.tsx aninhado onde as telas residem.
Piscada de título dinâmico - o título padrão é exibido antes que a busca seja concluída. Correção: Use um título esqueleto ou headerLargeTitle: false até que os dados sejam carregados; defina opções em useEffect.
router.push após o login duplica a autenticação na pilha de volta - os usuários deslizam para voltar para o login. Correção: router.replace('/(tabs)') após autenticação bem-sucedida.
Modal sem tratamento de back do Android - presentation: "modal" ainda respeita o back do hardware, mas sobreposições personalizadas podem não. Correção: Teste o back do Android; prefira rotas reais em vez de sobreposições de posição absoluta.
Deep link abre a pilha no meio da árvore sem índice - /orders/99 pode pular a tela da lista. Correção: Aceitável para notificações; use UI de fallback router.back() quando a pilha estiver vazia.

Alternativas

Alternativa	Use Quando	Não Use Quando
`Stack` (native-stack)	Push/pop padrão, cabeçalhos nativos, gestos	Você precisa de transições de elementos compartilhados entre pilhas (limitado)
`Tabs`	Seções de nível superior com barra de abas persistente	Assistente linear sem troca de seção
`Drawer`	Muitas seções, navegação focada em tablets	Aplicativos de celular com ≤4 destinos primários
Modal como rota (`presentation: "modal"`)	Formulários de tela inteira, fluxos de composição	Pequenas dicas ou dropdowns
Sobreposição imperativa (`react-native` Modal)	Alertas bloqueadores, seletores únicos	Navegação que deve aparecer no histórico/deep links
Pilha JS do React Navigation (`@react-navigation/stack`)	Animações de cartão personalizadas em configurações mais antigas	Projetos com SDK 57 mais recentes - native-stack é o padrão

FAQs

Como oculto o cabeçalho em uma tela?

// Em _layout.tsx
<Stack.Screen name="login" options={{ headerShown: false }} />
 
// Ou exporte do arquivo de rota
export const options = { headerShown: false };

Defina headerShown: false na tela específica - screenOptions pai ainda pode ser aplicado a irmãos.

Como adiciono um botão direito no cabeçalho?

import { Stack, router } from "expo-router";
import { Pressable, Text } from "react-native";
 
export default function EditScreen() {
  return (
    <>
      <Stack.Screen
        options={{
          headerRight: () => (
            <Pressable onPress={() => router.push("/preview")}>
              <Text>Pré-visualizar</Text>
            </Pressable>
          ),
        }}
      />
      {/* corpo da tela */}
    </>
  );
}

Use props de renderização headerLeft, headerRight ou headerTitle - mesma API do React Navigation.

Posso usar um componente de cabeçalho personalizado?

Sim - header: () => <MyHeader /> nas opções da tela. Prefira cabeçalhos de sistema de design para consistência. Oculte o padrão com headerShown: false e renderize o seu próprio no corpo da tela apenas quando o cabeçalho da pilha for insuficiente.

Como funciona o botão de voltar do hardware Android?

O botão de voltar do hardware remove a pilha atual. Na primeira tela da pilha raiz, o botão de voltar sai do aplicativo (ou vai para o plano de fundo). Teste pilhas aninhadas dentro de abas - o botão de voltar deve remover o detalhe antes de alternar as abas.

Como reinicio a pilha no logout?

import { router } from "expo-router";
 
router.replace("/(auth)/login");

replace remove rotas anteriores do histórico. Para reinícios complexos, remonte o navegador com uma key vinculada a userId no layout raiz.

Modais devem ser rotas ou React Native Modal?

Rotas quando o modal tem uma URL, deep link ou deve aparecer no histórico de navegação. RN Modal para UI efêmera sem caminho compartilhável. Documente a escolha da equipe em um ADR quando ambos os padrões aparecerem.

Como passo dados entre telas da pilha?

Parâmetros de URL para IDs e estado superficial (params: { id })
Armazenamento global (Zustand, TanStack Query) para entidades compartilhadas
Evite JSON grande em parâmetros - URLs são registradas e persistidas no estado de navegação

Veja Rotas Tipadas para tipagem de parâmetros.

Quais opções de animação o native-stack suporta?

Posso aninhar uma pilha dentro de outra pilha?

Sim - app/settings/_layout.tsx pode exportar <Stack> enquanto está dentro da pilha raiz. Limite a profundidade para duas pilhas (raiz + recurso) antes que a experiência do usuário e a depuração sofram.

Como desabilito o swipe-back em uma tela sensível?

<Stack.Screen name="confirm-payment" options={{ gestureEnabled: false }} />

Use para ações irreversíveis. Emparelhe com um botão de cancelar explícito para acessibilidade.

Relacionados

Noções Básicas do Expo Router - modelo mental do sistema de arquivos e _layout.tsx
Abas e Gavetas - aninhando pilhas sob abas
Link & href - destinos de push declarativos
Grupos de Rotas e Organizando app/ - padrão de grupo (modals)
../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - checklist de revisão
../architecture-design/adr-navigation-library-choice/adr-navigation-library-choice.md - Expo Router vs. escolha manual da biblioteca de navegação

Versões da Pilha: 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 expo-router

app/
├── _layout.tsx           # Pilha raiz
├── index.tsx
├── settings.tsx
└── orders/
    ├── _layout.tsx       # Pilha aninhada para /orders/*
    ├── index.tsx
    └── [id].tsx

// app/_layout.tsx
import { Stack } from "expo-router";
 
export default function RootLayout() {
  return (
    <Stack
      screenOptions={{
        headerShown: true,
        animation: "slide_from_right",
      }}
    >
      <Stack.Screen name="index" options={{ title: "Início" }} />
      <Stack.Screen name="settings" options={{ title: "Configurações" }} />
    </Stack>
  );
}

// app/orders/_layout.tsx
import { Stack } from "expo-router";
 
export default function OrdersLayout() {
  return (
    <Stack>
      <Stack.Screen name="index" options={{ title: "Pedidos" }} />
      <Stack.Screen name="[id]" options={{ title: "Pedido" }} />
    </Stack>
  );
}

Quando usar isso:

Fluxos lineares de detalhamento (lista → detalhe → editar)
Modais de tela inteira via presentation: "modal"
Ocultar cabeçalhos em telas de splash/autenticação com headerShown: false
Pilhas aninhadas dentro de abas quando uma aba precisa de seu próprio histórico de push

Exemplo de Trabalho

Uma pilha raiz com um splash de cabeçalho oculto, uma tela de configurações com um título dinâmico e uma pilha de pedidos aninhada.

// app/_layout.tsx
import { Stack } from "expo-router";
import { ThemeProvider } from "@/shared/theme";
 
export default function RootLayout() {
  return (
    <ThemeProvider>
      <Stack>
        <Stack.Screen name="index" options={{ headerShown: false }} />
        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
        <Stack.Screen
          name="settings"
          options={{
            title: "Configurações",
            presentation: "card",
          }}
        />
      </Stack>
    </ThemeProvider>
  );
}

// app/settings.tsx
import { useNavigation } from "expo-router";
import { useEffect } from "react";
import { ActivityIndicator, Text, View } from "react-native";
 
export default function SettingsScreen() {
  const navigation = useNavigation();
 
  useEffect(() => {
    navigation.setOptions({ title: "Configurações da Conta" });
  }, [navigation]);
 
  return (
    <View style={{ flex: 1, padding: 16 }}>
      <Text>Conteúdo das configurações</Text>
    </View>
  );
}

// app/orders/[id].tsx
import { useLocalSearchParams, Stack } from "expo-router";
import { useEffect, useState } from "react";
import { ActivityIndicator, Text, View } from "react-native";
 
export default function OrderDetailScreen() {
  const { id } = useLocalSearchParams<{ id: string }>();
  const [title, setTitle] = useState(`Pedido #${id}`);
 
  useEffect(() => {
    // Simula busca - então atualiza o cabeçalho via filho do layout
    const timer = setTimeout(() => setTitle(`Pedido ${id} - Enviado`), 400);
    return () => clearTimeout(timer);
  }, [id]);
 
  return (
    <>
      <Stack.Screen options={{ title }} />
      <View style={{ flex: 1, padding: 16 }}>
        <Text>Detalhe do pedido {id}</Text>
      </View>
    </>
  );
}

// Navega entre telas da pilha
import { Link, router } from "expo-router";
import { Pressable, Text, View } from "react-native";
 
export function HomeActions() {
  return (
    <View style={{ gap: 12 }}>
      <Link href="/settings">Configurações (declarativo)</Link>
      <Pressable onPress={() => router.push("/orders/42")}>
        <Text>Pedido 42 (imperativo)</Text>
      </Pressable>
    </View>
  );
}

Mergulho Profundo

Como o sistema de arquivos se torna uma pilha

app/orders/_layout.tsx  →  <Stack> envolve esta pasta
app/orders/index.tsx    →  rota inicial (fundo da pilha)
app/orders/[id].tsx     →  empurrado ao navegar para /orders/:id
app/orders/new.tsx      →  empurrado ao navegar para /orders/new

Expo Router registra automaticamente cada arquivo de rota como um Stack.Screen - <Stack.Screen name="..."> explícito é opcional, mas recomendado para opções
A rota inicial é a primeira tela correspondente na navegação; deep links podem abrir [id] diretamente
Arquivos irmãos compartilham um histórico de pilha - pastas sem _layout.tsx herdam o navegador pai

Camadas de configuração do cabeçalho

Camada	API	Precedência
Padrão do Navegador	`screenOptions` em `<Stack>`	Mais baixa
Filho do Layout	`<Stack.Screen options={...}>`	Média
Arquivo de Rota	`export const options = {...}`	Média
Tempo de Execução	`navigation.setOptions()` ou `<Stack.Screen options>` no render	Mais alta

// Opções estáticas por rota (co-localizadas)
export const options = {
  title: "Perfil",
  headerBackTitle: "Voltar",
};

Modos de apresentação

<Stack.Screen
  name="compose"
  options={{
    presentation: "modal",        // Modal de cartão iOS; tela inteira Android
    gestureEnabled: true,
    headerShown: true,
  }}
/>

card (padrão) - animação de push padrão
modal - apresentação de modal; emparelhe com um grupo de rotas (modals) para organização
transparentModal - sobrepõe a tela anterior (use com moderação - acessibilidade e o back do Android diferem)
fullScreenModal - modal de ponta a ponta no iOS

Aninhando pilhas sob abas

(tabs)/_layout.tsx     → Abas (barra de abas sempre visível)
(tabs)/orders/_layout  → Pilha (push apenas dentro da aba Pedidos)

Armadilhas

_layout.tsx ausente em uma pasta com várias telas - irmãos podem se achatar inesperadamente na pilha pai. Correção: Adicione orders/_layout.tsx com <Stack /> quando uma pasta tiver index + [id].
Nomes de tela duplicados de arquivos index - orders.tsx e orders/index.tsx entram em conflito. Correção: Escolha uma forma de URL por recurso.
headerShown: false na pilha raiz, mas esperando cabeçalhos aninhados - pilhas filhas devem definir headerShown: true explicitamente. Correção: Configure cabeçalhos no _layout.tsx aninhado onde as telas residem.
Piscada de título dinâmico - o título padrão é exibido antes que a busca seja concluída. Correção: Use um título esqueleto ou headerLargeTitle: false até que os dados sejam carregados; defina opções em useEffect.
router.push após o login duplica a autenticação na pilha de volta - os usuários deslizam para voltar para o login. Correção: router.replace('/(tabs)') após autenticação bem-sucedida.
Modal sem tratamento de back do Android - presentation: "modal" ainda respeita o back do hardware, mas sobreposições personalizadas podem não. Correção: Teste o back do Android; prefira rotas reais em vez de sobreposições de posição absoluta.
Deep link abre a pilha no meio da árvore sem índice - /orders/99 pode pular a tela da lista. Correção: Aceitável para notificações; use UI de fallback router.back() quando a pilha estiver vazia.

Alternativas

Alternativa	Use Quando	Não Use Quando
`Stack` (native-stack)	Push/pop padrão, cabeçalhos nativos, gestos	Você precisa de transições de elementos compartilhados entre pilhas (limitado)
`Tabs`	Seções de nível superior com barra de abas persistente	Assistente linear sem troca de seção
`Drawer`	Muitas seções, navegação focada em tablets	Aplicativos de celular com ≤4 destinos primários
Modal como rota (`presentation: "modal"`)	Formulários de tela inteira, fluxos de composição	Pequenas dicas ou dropdowns
Sobreposição imperativa (`react-native` Modal)	Alertas bloqueadores, seletores únicos	Navegação que deve aparecer no histórico/deep links
Pilha JS do React Navigation (`@react-navigation/stack`)	Animações de cartão personalizadas em configurações mais antigas	Projetos com SDK 57 mais recentes - native-stack é o padrão

FAQs

Como oculto o cabeçalho em uma tela?

// Em _layout.tsx
<Stack.Screen name="login" options={{ headerShown: false }} />
 
// Ou exporte do arquivo de rota
export const options = { headerShown: false };

Defina headerShown: false na tela específica - screenOptions pai ainda pode ser aplicado a irmãos.

Como adiciono um botão direito no cabeçalho?

import { Stack, router } from "expo-router";
import { Pressable, Text } from "react-native";
 
export default function EditScreen() {
  return (
    <>
      <Stack.Screen
        options={{
          headerRight: () => (
            <Pressable onPress={() => router.push("/preview")}>
              <Text>Pré-visualizar</Text>
            </Pressable>
          ),
        }}
      />
      {/* corpo da tela */}
    </>
  );
}

Use props de renderização headerLeft, headerRight ou headerTitle - mesma API do React Navigation.

Posso usar um componente de cabeçalho personalizado?

Como funciona o botão de voltar do hardware Android?

Como reinicio a pilha no logout?

import { router } from "expo-router";
 
router.replace("/(auth)/login");

replace remove rotas anteriores do histórico. Para reinícios complexos, remonte o navegador com uma key vinculada a userId no layout raiz.

Modais devem ser rotas ou React Native Modal?

Como passo dados entre telas da pilha?

Parâmetros de URL para IDs e estado superficial (params: { id })
Armazenamento global (Zustand, TanStack Query) para entidades compartilhadas
Evite JSON grande em parâmetros - URLs são registradas e persistidas no estado de navegação

Veja Rotas Tipadas para tipagem de parâmetros.

Quais opções de animação o native-stack suporta?

Posso aninhar uma pilha dentro de outra pilha?

Como desabilito o swipe-back em uma tela sensível?

<Stack.Screen name="confirm-payment" options={{ gestureEnabled: false }} />

Use para ações irreversíveis. Emparelhe com um botão de cancelar explícito para acessibilidade.

Relacionados

Noções Básicas do Expo Router - modelo mental do sistema de arquivos e _layout.tsx
Abas e Gavetas - aninhando pilhas sob abas
Link & href - destinos de push declarativos
Grupos de Rotas e Organizando app/ - padrão de grupo (modals)
../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - checklist de revisão
../architecture-design/adr-navigation-library-choice/adr-navigation-library-choice.md - Expo Router vs. escolha manual da biblioteca de navegação

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

Navegação em Pilha

Buscar na documentação

Navegação em Pilha