Abas Nativas

Q: Como migro de Abas JavaScript para NativeTabs?

1. Substitua import { Tabs } por NativeTabs de expo-router/unstable-native-tabs. 2. Adicione NativeTabs.Trigger para cada antigo Tabs.Screen. 3. Mova os ícones para NativeTabs.Trigger.Icon (API composta SDK 55+). 4. Mantenha os stacks _layout.tsx por aba inalterados.

Q: Abas nativas podem usar rotas tipadas do expo-router?

Sim - name em Trigger corresponde ao arquivo de rota (index, settings, nomes de pastas). Link href="/settings/account" funciona da mesma forma que com abas JavaScript.

Q: Como os badges são atualizados com novas mensagens?

Renderize novamente NativeTabs.Trigger.Badge quando a contagem de não lidas mudar. O badge é declarativo - sem API imperativa. Ponto de badge vazio: sem filhos.

Q: Por que os ícones selecionados parecem os mesmos no Android?

Variantes selected distintas para src / md exigem SDK 56+ e react-native-screens 4.25+. Atualize ou use @react-native-vector-icons/get-image com glifos separados.

Q: Native tabs vs. abas compostas na tela?

NativeTabs - navegação em nível de rota; cada aba é uma URL. Abas compostas (padrões de componentes) - alternância de painel local dentro de uma tela. Veja ../component-patterns/compound-components/compound-components.md.

Q: NativeTabs está pronto para produção?

Documentado como alpha - a API pode mudar. Adequado para equipes que aceitam mudanças de SDK e testam em dispositivos reais a cada lançamento. Use Tabs JavaScript estável quando a conformidade exigir APIs de navegação fixas.

Barras de abas nativas via API de abas nativas do Expo Router. NativeTabs de expo-router/unstable-native-tabs renderiza barras de abas UIKit / Material - incluindo o estilo de vidro líquido do iOS - em vez de abas desenhadas em JavaScript. A API está em alpha no SDK 57; fixe o comportamento em QA antes de lançar UX de produção que dependa de casos extremos.

Receita

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

app/
├── _layout.tsx              # Raiz do NativeTabs
├── index.tsx                # primeira aba
├── explore.tsx
└── settings/
    ├── _layout.tsx          # Stack dentro da aba
    └── index.tsx

// app/_layout.tsx - SDK 57 (API composta SDK 55+)
import { NativeTabs } from "expo-router/unstable-native-tabs";
 
export default function TabLayout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="index">
        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
        <NativeTabs.Trigger.Icon
          sf={{ default: "house", selected: "house.fill" }}
          md="home"
        />
      </NativeTabs.Trigger>
 
      <NativeTabs.Trigger name="explore">
        <NativeTabs.Trigger.Label>Explore</NativeTabs.Trigger.Label>
        <NativeTabs.Trigger.Icon sf="safari" md="explore" />
      </NativeTabs.Trigger>
 
      <NativeTabs.Trigger name="settings">
        <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>
        <NativeTabs.Trigger.Icon sf="gear" md="settings" />
        <NativeTabs.Trigger.Badge>2</NativeTabs.Trigger.Badge>
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}

// app/settings/_layout.tsx - stack por aba (cabeçalhos + push)
import { Stack } from "expo-router";
 
export default function SettingsStack() {
  return (
    <Stack>
      <Stack.Screen name="index" options={{ title: "Settings" }} />
      <Stack.Screen name="account" options={{ title: "Account" }} />
    </Stack>
  );
}

Quando usar isso:

Chrome de aba nativo da plataforma - vidro líquido, SF Symbols, blur do sistema
Acessibilidade - comportamento VoiceOver / TalkBack da barra de abas do sistema
Desempenho - menos trabalho de layout em JS em comparação com abas personalizadas
Badges e scroll-to-top nativo ao tocar novamente na aba (Android SDK 55+)

Exemplo de Trabalho

Abas nativas com stacks por aba, badge dinâmico, visibilidade condicional de aba e cores dinâmicas do iOS.

// app/_layout.tsx
import { DynamicColorIOS } from "react-native";
import { NativeTabs } from "expo-router/unstable-native-tabs";
import { useUnreadCount } from "@/features/inbox";
 
export default function TabLayout() {
  const unread = useUnreadCount();
  const showInbox = true; // feature flag - definido antes da montagem, não alternado ao vivo
 
  return (
    <NativeTabs
      labelStyle={{
        color: DynamicColorIOS({ dark: "white", light: "black" }),
      }}
      tintColor={DynamicColorIOS({ dark: "white", light: "#007AFF" })}
    >
      <NativeTabs.Trigger name="index" disablePopToTop={false}>
        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
        <NativeTabs.Trigger.Icon
          sf={{ default: "house", selected: "house.fill" }}
          md={{ default: "home", selected: "home" }}
        />
      </NativeTabs.Trigger>
 
      <NativeTabs.Trigger name="inbox" hidden={!showInbox}>
        <NativeTabs.Trigger.Label>Inbox</NativeTabs.Trigger.Label>
        <NativeTabs.Trigger.Icon sf="tray" md="inbox" />
        {unread > 0 && <NativeTabs.Trigger.Badge>{unread > 9 ? "9+" : unread}</NativeTabs.Trigger.Badge>}
      </NativeTabs.Trigger>
 
      <NativeTabs.Trigger name="settings">
        <NativeTabs.Trigger.Label hidden />
        <NativeTabs.Trigger.Icon sf="gear" md="settings" />
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}

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

// Ocultando a barra de abas na tela focada (prop hidden do NativeTabs SDK 55+)
import { createContext, use, useState } from "react";
import { NativeTabs } from "expo-router/unstable-native-tabs";
import { useFocusEffect } from "expo-router";
 
export const TabBarContext = createContext({
  setTabBarHidden: (_hidden: boolean) => {},
});
 
export default function TabLayout() {
  const [hidden, setTabBarHidden] = useState(false);
 
  return (
    <TabBarContext value={{ setTabBarHidden }}>
      <NativeTabs hidden={hidden}>
        <NativeTabs.Trigger name="index">
          <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
        </NativeTabs.Trigger>
      </NativeTabs>
    </TabBarContext>
  );
}
 
// Na tela imersiva:
export function useHideTabBarOnFocus() {
  const { setTabBarHidden } = use(TabBarContext);
  useFocusEffect(() => {
    setTabBarHidden(true);
    return () => setTabBarHidden(false);
  });
}

Mergulho Profundo

Abas Nativas vs. Abas JavaScript

	`NativeTabs`	`Tabs` (expo-router)
Renderização da barra de abas	Sistema Nativo	React Navigation JS
Registro de rotas	`Trigger` manual por rota	Automático a partir de arquivos `app/`
UI de barra de abas personalizada	Limitada	Prop `tabBar`, totalmente personalizada
Stack dentro da aba	✅ Recomendado	✅
`Tabs.Protected`	Usa `Stack.Protected` raiz envolvendo as abas	✅ Integrado
Status	Alpha (SDK 54+)	Estável

Fontes de Ícones

<NativeTabs.Trigger.Icon
  sf={{ default: "star", selected: "star.fill" }}  // SF Symbols (iOS)
  md={{ default: "star", selected: "star" }}     // Material Symbols (Android)
  src={require("@/assets/icon.png")}             // Imagem personalizada
  xcasset="home-icon"                            // Catálogo de assets do iOS (SDK 55+)
  renderingMode="template"                       // Cores de tinta vs originais do iOS
/>

sf tem precedência no iOS sobre src; Android usa src / md.
Ícones selecionados distintos no Android exigem SDK 56+ / react-native-screens 4.25+.
Fontes de ícones vetoriais - rasterize com @react-native-vector-icons/get-image no escopo do módulo.

Props de Interação de Aba (SDK 55+)

Prop	Plataforma	Comportamento
`disablePopToTop`	Android	O toque repetido não remove o stack para a raiz
`disableScrollToTop`	Android	O toque repetido não rola a lista para o topo
`hidden`	Ambos	A aba não é exibida; não navegável
`disabled`	SDK 56+	A aba é visível, mas não clicável; a navegação JS ainda funciona

Ocultar abas dinamicamente desmonta o navegador e redefine o estado. Alterne a visibilidade antes da primeira renderização ou quando a barra de abas não estiver visível.

Aninhamento com Stack Raiz

// app/_layout.tsx na raiz do projeto é frequentemente um Stack, não NativeTabs
import { Stack } from "expo-router";
 
export default function RootLayout() {
  return (
    <Stack screenOptions={{ headerShown: false }}>
      <Stack.Screen name="(tabs)" />
      <Stack.Screen name="compose" options={{ presentation: "modal" }} />
    </Stack>
  );
}
 
// app/(tabs)/_layout.tsx - NativeTabs vive um nível abaixo

Veja Navegadores Aninhados.

Armadilhas

Esquecer NativeTabs.Trigger - Arquivos em app/ não aparecem na barra de abas automaticamente. Correção: Adicione um Trigger para cada aba roteável.
Usar disabled para controle de autenticação - router.push('/settings') ignora o disabled. Correção: Stack.Protected na raiz.
Alternar hidden em tempo de execução - Desmonta o navegador; perde o estado do stack. Correção: Flags de recursos resolvidos antes da primeira renderização.
Branding personalizado da barra de abas - Abas nativas seguem o chrome do sistema. Correção: Abas personalizadas em JavaScript ou Tabs com a prop tabBar.
Esperar Tabs.Protected em NativeTabs - Use guardas de stack externas. Correção: Envolva o grupo (tabs) em Stack.Protected.
Mudanças de quebra na API Alpha - Fixe expo-router e leia o changelog do SDK antes de atualizar. Correção: Teste ícones de aba, badges e comportamento de retorno a cada atualização de SDK.

Alternativas

Alternativa	Use Quando	Não Use Quando
`NativeTabs`	Aparência nativa do sistema, vidro líquido iOS	UI de barra de abas totalmente personalizada
`Tabs` JavaScript	`Tabs.Protected`, `tabBar` personalizado	Você precisa de fidelidade da barra de abas UIKit
Abas personalizadas (`expo-router/ui`)	Chrome de marca com foco em marketing	Você quer manutenção zero de primitivas de aba
Navegação por bottom sheet	Superfície de ação primária única	Padrão de produto de 4 abas principal no celular
Sem abas - apenas drawer	Muitas seções, poucas de nível superior	Padrão de produto de 4 abas principal no celular

FAQs

Como migro de Abas JavaScript para NativeTabs?

Substitua import { Tabs } por NativeTabs de expo-router/unstable-native-tabs.
Adicione NativeTabs.Trigger para cada antigo Tabs.Screen.
Mova os ícones para NativeTabs.Trigger.Icon (API composta SDK 55+).
Mantenha os stacks _layout.tsx por aba inalterados.

Abas nativas podem usar rotas tipadas do expo-router?

Sim - name em Trigger corresponde ao arquivo de rota (index, settings, nomes de pastas).
Link href="/settings/account" funciona da mesma forma que com abas JavaScript.

Como os badges são atualizados com novas mensagens?

Renderize novamente NativeTabs.Trigger.Badge quando a contagem de não lidas mudar.
O badge é declarativo - sem API imperativa.
Ponto de badge vazio: <NativeTabs.Trigger.Badge /> sem filhos.

Por que os ícones selecionados parecem os mesmos no Android?

Variantes selected distintas para src / md exigem SDK 56+ e react-native-screens 4.25+.
Atualize ou use @react-native-vector-icons/get-image com glifos separados.

Native tabs vs. abas compostas na tela?

NativeTabs - navegação em nível de rota; cada aba é uma URL.
Abas compostas (padrões de componentes) - alternância de painel local dentro de uma tela.
Veja ../component-patterns/compound-components/compound-components.md.

NativeTabs está pronto para produção?

Documentado como alpha - a API pode mudar.
Adequado para equipes que aceitam mudanças de SDK e testam em dispositivos reais a cada lançamento.
Use Tabs JavaScript estável quando a conformidade exigir APIs de navegação fixas.

Relacionados

Navegadores Aninhados - stacks dentro de abas nativas
Rotas Protegidas e Middleware - autenticação acima do shell de abas
Visão Dividida e Layouts de Tablet - padrões de tablet além das abas inferiores
../expo-router/tabs-and-drawers/tabs-and-drawers.md - base de abas JavaScript
../expo-router/stack-navigation/stack-navigation.md - cabeçalhos de stack por aba
../ios-platform/ios-basics-for-rn-devs/ios-basics-for-rn-devs.md - contexto de SF Symbols e HIG

Versões do 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.

app/
├── _layout.tsx              # Raiz do NativeTabs
├── index.tsx                # primeira aba
├── explore.tsx
└── settings/
    ├── _layout.tsx          # Stack dentro da aba
    └── index.tsx

// app/_layout.tsx - SDK 57 (API composta SDK 55+)
import { NativeTabs } from "expo-router/unstable-native-tabs";
 
export default function TabLayout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="index">
        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
        <NativeTabs.Trigger.Icon
          sf={{ default: "house", selected: "house.fill" }}
          md="home"
        />
      </NativeTabs.Trigger>
 
      <NativeTabs.Trigger name="explore">
        <NativeTabs.Trigger.Label>Explore</NativeTabs.Trigger.Label>
        <NativeTabs.Trigger.Icon sf="safari" md="explore" />
      </NativeTabs.Trigger>
 
      <NativeTabs.Trigger name="settings">
        <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>
        <NativeTabs.Trigger.Icon sf="gear" md="settings" />
        <NativeTabs.Trigger.Badge>2</NativeTabs.Trigger.Badge>
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}

// app/settings/_layout.tsx - stack por aba (cabeçalhos + push)
import { Stack } from "expo-router";
 
export default function SettingsStack() {
  return (
    <Stack>
      <Stack.Screen name="index" options={{ title: "Settings" }} />
      <Stack.Screen name="account" options={{ title: "Account" }} />
    </Stack>
  );
}

Quando usar isso:

Chrome de aba nativo da plataforma - vidro líquido, SF Symbols, blur do sistema
Acessibilidade - comportamento VoiceOver / TalkBack da barra de abas do sistema
Desempenho - menos trabalho de layout em JS em comparação com abas personalizadas
Badges e scroll-to-top nativo ao tocar novamente na aba (Android SDK 55+)

Exemplo de Trabalho

Abas nativas com stacks por aba, badge dinâmico, visibilidade condicional de aba e cores dinâmicas do iOS.

// app/_layout.tsx
import { DynamicColorIOS } from "react-native";
import { NativeTabs } from "expo-router/unstable-native-tabs";
import { useUnreadCount } from "@/features/inbox";
 
export default function TabLayout() {
  const unread = useUnreadCount();
  const showInbox = true; // feature flag - definido antes da montagem, não alternado ao vivo
 
  return (
    <NativeTabs
      labelStyle={{
        color: DynamicColorIOS({ dark: "white", light: "black" }),
      }}
      tintColor={DynamicColorIOS({ dark: "white", light: "#007AFF" })}
    >
      <NativeTabs.Trigger name="index" disablePopToTop={false}>
        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
        <NativeTabs.Trigger.Icon
          sf={{ default: "house", selected: "house.fill" }}
          md={{ default: "home", selected: "home" }}
        />
      </NativeTabs.Trigger>
 
      <NativeTabs.Trigger name="inbox" hidden={!showInbox}>
        <NativeTabs.Trigger.Label>Inbox</NativeTabs.Trigger.Label>
        <NativeTabs.Trigger.Icon sf="tray" md="inbox" />
        {unread > 0 && <NativeTabs.Trigger.Badge>{unread > 9 ? "9+" : unread}</NativeTabs.Trigger.Badge>}
      </NativeTabs.Trigger>
 
      <NativeTabs.Trigger name="settings">
        <NativeTabs.Trigger.Label hidden />
        <NativeTabs.Trigger.Icon sf="gear" md="settings" />
      </NativeTabs.Trigger>
    </NativeTabs>
  );
}

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

// Ocultando a barra de abas na tela focada (prop hidden do NativeTabs SDK 55+)
import { createContext, use, useState } from "react";
import { NativeTabs } from "expo-router/unstable-native-tabs";
import { useFocusEffect } from "expo-router";
 
export const TabBarContext = createContext({
  setTabBarHidden: (_hidden: boolean) => {},
});
 
export default function TabLayout() {
  const [hidden, setTabBarHidden] = useState(false);
 
  return (
    <TabBarContext value={{ setTabBarHidden }}>
      <NativeTabs hidden={hidden}>
        <NativeTabs.Trigger name="index">
          <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
        </NativeTabs.Trigger>
      </NativeTabs>
    </TabBarContext>
  );
}
 
// Na tela imersiva:
export function useHideTabBarOnFocus() {
  const { setTabBarHidden } = use(TabBarContext);
  useFocusEffect(() => {
    setTabBarHidden(true);
    return () => setTabBarHidden(false);
  });
}

Mergulho Profundo

Abas Nativas vs. Abas JavaScript

	`NativeTabs`	`Tabs` (expo-router)
Renderização da barra de abas	Sistema Nativo	React Navigation JS
Registro de rotas	`Trigger` manual por rota	Automático a partir de arquivos `app/`
UI de barra de abas personalizada	Limitada	Prop `tabBar`, totalmente personalizada
Stack dentro da aba	✅ Recomendado	✅
`Tabs.Protected`	Usa `Stack.Protected` raiz envolvendo as abas	✅ Integrado
Status	Alpha (SDK 54+)	Estável

Fontes de Ícones

<NativeTabs.Trigger.Icon
  sf={{ default: "star", selected: "star.fill" }}  // SF Symbols (iOS)
  md={{ default: "star", selected: "star" }}     // Material Symbols (Android)
  src={require("@/assets/icon.png")}             // Imagem personalizada
  xcasset="home-icon"                            // Catálogo de assets do iOS (SDK 55+)
  renderingMode="template"                       // Cores de tinta vs originais do iOS
/>

sf tem precedência no iOS sobre src; Android usa src / md.
Ícones selecionados distintos no Android exigem SDK 56+ / react-native-screens 4.25+.
Fontes de ícones vetoriais - rasterize com @react-native-vector-icons/get-image no escopo do módulo.

Props de Interação de Aba (SDK 55+)

Prop	Plataforma	Comportamento
`disablePopToTop`	Android	O toque repetido não remove o stack para a raiz
`disableScrollToTop`	Android	O toque repetido não rola a lista para o topo
`hidden`	Ambos	A aba não é exibida; não navegável
`disabled`	SDK 56+	A aba é visível, mas não clicável; a navegação JS ainda funciona

Ocultar abas dinamicamente desmonta o navegador e redefine o estado. Alterne a visibilidade antes da primeira renderização ou quando a barra de abas não estiver visível.

Aninhamento com Stack Raiz

// app/_layout.tsx na raiz do projeto é frequentemente um Stack, não NativeTabs
import { Stack } from "expo-router";
 
export default function RootLayout() {
  return (
    <Stack screenOptions={{ headerShown: false }}>
      <Stack.Screen name="(tabs)" />
      <Stack.Screen name="compose" options={{ presentation: "modal" }} />
    </Stack>
  );
}
 
// app/(tabs)/_layout.tsx - NativeTabs vive um nível abaixo

Veja Navegadores Aninhados.

Armadilhas

Esquecer NativeTabs.Trigger - Arquivos em app/ não aparecem na barra de abas automaticamente. Correção: Adicione um Trigger para cada aba roteável.
Usar disabled para controle de autenticação - router.push('/settings') ignora o disabled. Correção: Stack.Protected na raiz.
Alternar hidden em tempo de execução - Desmonta o navegador; perde o estado do stack. Correção: Flags de recursos resolvidos antes da primeira renderização.
Branding personalizado da barra de abas - Abas nativas seguem o chrome do sistema. Correção: Abas personalizadas em JavaScript ou Tabs com a prop tabBar.
Esperar Tabs.Protected em NativeTabs - Use guardas de stack externas. Correção: Envolva o grupo (tabs) em Stack.Protected.
Mudanças de quebra na API Alpha - Fixe expo-router e leia o changelog do SDK antes de atualizar. Correção: Teste ícones de aba, badges e comportamento de retorno a cada atualização de SDK.

Alternativas

Alternativa	Use Quando	Não Use Quando
`NativeTabs`	Aparência nativa do sistema, vidro líquido iOS	UI de barra de abas totalmente personalizada
`Tabs` JavaScript	`Tabs.Protected`, `tabBar` personalizado	Você precisa de fidelidade da barra de abas UIKit
Abas personalizadas (`expo-router/ui`)	Chrome de marca com foco em marketing	Você quer manutenção zero de primitivas de aba
Navegação por bottom sheet	Superfície de ação primária única	Padrão de produto de 4 abas principal no celular
Sem abas - apenas drawer	Muitas seções, poucas de nível superior	Padrão de produto de 4 abas principal no celular

FAQs

Como migro de Abas JavaScript para NativeTabs?

Substitua import { Tabs } por NativeTabs de expo-router/unstable-native-tabs.
Adicione NativeTabs.Trigger para cada antigo Tabs.Screen.
Mova os ícones para NativeTabs.Trigger.Icon (API composta SDK 55+).
Mantenha os stacks _layout.tsx por aba inalterados.

Abas nativas podem usar rotas tipadas do expo-router?

Sim - name em Trigger corresponde ao arquivo de rota (index, settings, nomes de pastas).
Link href="/settings/account" funciona da mesma forma que com abas JavaScript.

Como os badges são atualizados com novas mensagens?

Renderize novamente NativeTabs.Trigger.Badge quando a contagem de não lidas mudar.
O badge é declarativo - sem API imperativa.
Ponto de badge vazio: <NativeTabs.Trigger.Badge /> sem filhos.

Por que os ícones selecionados parecem os mesmos no Android?

Variantes selected distintas para src / md exigem SDK 56+ e react-native-screens 4.25+.
Atualize ou use @react-native-vector-icons/get-image com glifos separados.

Native tabs vs. abas compostas na tela?

NativeTabs - navegação em nível de rota; cada aba é uma URL.
Abas compostas (padrões de componentes) - alternância de painel local dentro de uma tela.
Veja ../component-patterns/compound-components/compound-components.md.

NativeTabs está pronto para produção?

Documentado como alpha - a API pode mudar.
Adequado para equipes que aceitam mudanças de SDK e testam em dispositivos reais a cada lançamento.
Use Tabs JavaScript estável quando a conformidade exigir APIs de navegação fixas.

Relacionados

Navegadores Aninhados - stacks dentro de abas nativas
Rotas Protegidas e Middleware - autenticação acima do shell de abas
Visão Dividida e Layouts de Tablet - padrões de tablet além das abas inferiores
../expo-router/tabs-and-drawers/tabs-and-drawers.md - base de abas JavaScript
../expo-router/stack-navigation/stack-navigation.md - cabeçalhos de stack por aba
../ios-platform/ios-basics-for-rn-devs/ios-basics-for-rn-devs.md - contexto de SF Symbols e HIG

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

Abas Nativas

Buscar na documentação

Abas Nativas