expo / skills

expo-router

Navigation and routing with Expo Router: file-based and dynamic routes, Link previews and context menus, native Stack, modals and form sheets, NativeTabs, headers, toolbars and search bars.

View source Expo React Native Architecture Interaction

Install

npx skills add https://github.com/expo/skills --skill expo-router

Native Tabs

Always prefer NativeTabs from 'expo-router/unstable-native-tabs' for the best iOS experience.

SDK 54+. SDK 55 recommended.

SDK Compatibility

Aspect	SDK 54	SDK 55+
Import	`import { NativeTabs, Icon, Label, Badge, VectorIcon }`	`import { NativeTabs }` only
Icon	`<Icon sf="house.fill" />`	`<NativeTabs.Trigger.Icon sf="house.fill" />`
Label	`<Label>Home</Label>`	`<NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>`
Badge	`<Badge>9+</Badge>`	`<NativeTabs.Trigger.Badge>9+</NativeTabs.Trigger.Badge>`
Android icons	`drawable` prop	`md` prop (Material Symbols)

All examples below use SDK 55 syntax. For SDK 54, replace NativeTabs.Trigger.Icon/Label/Badge with standalone Icon, Label, Badge imports.

Basic Usage

tsx

import { NativeTabs } from "expo-router/unstable-native-tabs";
export default function TabLayout() {  return (    <NativeTabs minimizeBehavior="onScrollDown">      <NativeTabs.Trigger name="index">        <NativeTabs.Trigger.Icon sf="house.fill" md="home" />        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>        <NativeTabs.Trigger.Badge>9+</NativeTabs.Trigger.Badge>      </NativeTabs.Trigger>      <NativeTabs.Trigger name="settings">        <NativeTabs.Trigger.Icon sf="gear" md="settings" />        <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>      </NativeTabs.Trigger>      <NativeTabs.Trigger name="(search)" role="search">        <NativeTabs.Trigger.Label>Search</NativeTabs.Trigger.Label>      </NativeTabs.Trigger>    </NativeTabs>  );}

Rules

You must include a trigger for each tab
The NativeTabs.Trigger 'name' must match the route name, including parentheses (e.g. <NativeTabs.Trigger name="(search)">)
Prefer search tab to be last in the list so it can combine with the search bar
Use the 'role' prop for common tab types
Tabs must be static — no dynamic addition/removal at runtime (remounts navigator, loses state)

Platform Features

Native Tabs use platform-specific tab bar implementations:

iOS 26+: Liquid glass effects with system-native appearance
Android: Material 3 bottom navigation
Better performance and native feel

Icon Component

tsx

// SF Symbol (iOS) + Material Symbol (Android)<NativeTabs.Trigger.Icon sf="house.fill" md="home" />
// State variants<NativeTabs.Trigger.Icon sf={{ default: "house", selected: "house.fill" }} md="home" />
// Custom image<NativeTabs.Trigger.Icon src={require('./icon.png')} />
// Xcode asset catalog — iOS only (SDK 55+)<NativeTabs.Trigger.Icon xcasset="home-icon" /><NativeTabs.Trigger.Icon xcasset={{ default: "home-outline", selected: "home-filled" }} />
// Rendering mode — iOS only (SDK 55+)<NativeTabs.Trigger.Icon src={require('./icon.png')} renderingMode="template" /><NativeTabs.Trigger.Icon src={require('./gradient.png')} renderingMode="original" />

renderingMode: "template" applies tint color (single-color icons), "original" preserves source colors (gradients). Android always uses original.

Label & Badge

tsx

// Label<NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label><NativeTabs.Trigger.Label hidden>Home</NativeTabs.Trigger.Label>  {/* icon-only tab */}
// Badge<NativeTabs.Trigger.Badge>9+</NativeTabs.Trigger.Badge><NativeTabs.Trigger.Badge />  {/* dot indicator */}

iOS 26 Features

Liquid Glass Tab Bar

The tab bar automatically adopts liquid glass appearance on iOS 26+.

Minimize on Scroll

Search Tab

Note: Place search tab last for best UX.

Role Prop

Use semantic roles for special tab types:

Customization

Tint Color

Dynamic Colors (iOS)

Use DynamicColorIOS for colors that adapt to liquid glass:

tsx

import { DynamicColorIOS, Platform } from 'react-native';
const adaptiveBlue = Platform.select({  ios: DynamicColorIOS({ light: '#007AFF', dark: '#0A84FF' }),  default: '#007AFF',});
<NativeTabs tintColor={adaptiveBlue}>

Conditional Tabs

Don't hide the tabs when they are visible - toggling visibility remounts the navigator; Do it only during the initial render.

Note: Hidden tabs cannot be navigated to!

Behavior Options

tsx

<NativeTabs.Trigger  name="home"  disablePopToTop           // Don't pop stack when tapping active tab  disableScrollToTop        // Don't scroll to top when tapping active tab  disableAutomaticContentInsets  // Opt out of automatic safe area insets (SDK 55+)>

Hidden Tab Bar (SDK 55+)

Use hidden prop on NativeTabs to hide the entire tab bar dynamically:

Bottom Accessory (SDK 55+)

NativeTabs.BottomAccessory renders content above the tab bar (iOS 26+). Uses usePlacement() to adapt between 'regular' and 'inline' layouts.

Important: Two instances render simultaneously — store state outside the component (props, context, or external store).

tsx

import { NativeTabs } from "expo-router/unstable-native-tabs";import { useState } from "react";import { Pressable, Text, View } from "react-native";
function MiniPlayer({  isPlaying,  onToggle,}: {  isPlaying: boolean;  onToggle: () => void;}) {  const placement = NativeTabs.BottomAccessory.usePlacement();  if (placement === "inline") {    return (      <Pressable onPress={onToggle}>        <SymbolView name={isPlaying ? "pause.fill" : "play.fill"} />      </Pressable>    );  }  return <View>{/* full player UI */}</View>;}
export default function TabLayout() {  const [isPlaying, setIsPlaying] = useState(false);  return (    <NativeTabs>      <NativeTabs.BottomAccessory>        <MiniPlayer          isPlaying={isPlaying}          onToggle={() => setIsPlaying(!isPlaying)}        />      </NativeTabs.BottomAccessory>      <NativeTabs.Trigger name="index">        <NativeTabs.Trigger.Icon sf="house.fill" md="home" />        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>      </NativeTabs.Trigger>    </NativeTabs>  );}

Safe Area Handling (SDK 55+)

SDK 55 handles safe areas automatically:

Android: Content wrapped in SafeAreaView (bottom inset)
iOS: First ScrollView gets automatic contentInsetAdjustmentBehavior

To opt out per-tab, use disableAutomaticContentInsets and manage manually:

tsx

// In the screenimport { SafeAreaView } from "react-native-screens/experimental";
export default function HomeScreen() {  return (    <SafeAreaView edges={{ bottom: true }} style={{ flex: 1 }}>      {/* content */}    </SafeAreaView>  );}

Using Vector Icons

If you must use @expo/vector-icons instead of SF Symbols:

tsx

import { NativeTabs } from "expo-router/unstable-native-tabs";import Ionicons from "@expo/vector-icons/Ionicons";
<NativeTabs.Trigger name="home">  <NativeTabs.Trigger.VectorIcon vector={Ionicons} name="home" />  <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label></NativeTabs.Trigger>

Prefer SF Symbols + md prop over vector icons for native feel.

If you are using SDK 55 and later use the md prop to specify Material Symbols used on Android.

Structure with Stacks

Native tabs don't render headers. Nest Stacks inside each tab for navigation headers:

tsx

// app/(tabs)/_layout.tsximport { NativeTabs } from "expo-router/unstable-native-tabs";
export default function TabLayout() {  return (    <NativeTabs>      <NativeTabs.Trigger name="(home)">        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>        <NativeTabs.Trigger.Icon sf="house.fill" md="home" />      </NativeTabs.Trigger>    </NativeTabs>  );}
// app/(tabs)/(home)/_layout.tsximport Stack from "expo-router/stack";
export default function HomeStack() {  return (    <Stack>      <Stack.Screen        name="index"        options={{ title: "Home", headerLargeTitleEnabled: true }}      />      <Stack.Screen name="details" options={{ title: "Details" }} />    </Stack>  );}

Custom Web Layout

Use platform-specific files for separate native and web tab layouts:

Or extract to a component: components/app-tabs.tsx + components/app-tabs.web.tsx.

Migration from JS Tabs

Before (JS Tabs)

tsx

import { Tabs } from "expo-router";
<Tabs>  <Tabs.Screen    name="index"    options={{      title: "Home",      tabBarIcon: ({ color }) => <IconSymbol name="house.fill" color={color} />,      tabBarBadge: 3,    }}  /></Tabs>;

After (Native Tabs)

tsx

import { NativeTabs } from "expo-router/unstable-native-tabs";
<NativeTabs>  <NativeTabs.Trigger name="index">    <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>    <NativeTabs.Trigger.Icon sf="house.fill" md="home" />    <NativeTabs.Trigger.Badge>3</NativeTabs.Trigger.Badge>  </NativeTabs.Trigger></NativeTabs>;

Key Differences

JS Tabs	Native Tabs
`<Tabs.Screen>`	`<NativeTabs.Trigger>`
`options={{ title }}`	`<NativeTabs.Trigger.Label>`
`options={{ tabBarIcon }}`	`<NativeTabs.Trigger.Icon>`
`tabBarBadge` option	`<NativeTabs.Trigger.Badge>`
Props-based API	Component-based API
Headers built-in	Nest `<Stack>` for headers

Limitations

Android: Maximum 5 tabs (Material Design constraint)
Nesting: Native tabs cannot nest inside other native tabs
Tab bar height: Cannot be measured programmatically
FlatList transparency: Use disableTransparentOnScrollEdge to fix issues
Dynamic tabs: Tabs must be static; changes remount navigator and lose state

Keyboard Handling (Android)

Configure in app.json:

Common Issues

Icons not showing on Android: Add md prop (SDK 55) or use VectorIcon
Headers missing: Nest a Stack inside each tab group
Trigger name mismatch: name must match exact route name including parentheses
Badge not visible: Badge must be a child of Trigger, not a prop
Tab bar transparent on iOS 18 and earlier: If the screen uses a ScrollView or FlatList, make sure it is the first opaque child of the screen component. If it needs to be wrapped in another View, ensure the wrapper uses collapsable={false}. If the screen does not use a ScrollView or FlatList, set disableTransparentOnScrollEdge to true in the NativeTabs.Trigger options, to make the tab bar opaque.
Scroll to top not working: Ensure disableScrollToTop is not set on the active tab's Trigger and ScrollView is the first child of the screen component.
Header buttons flicker when navigating between tabs: Make sure the app is wrapped in a ThemeProvider

tsx

import {  ThemeProvider,  DarkTheme,  DefaultTheme,} from "expo-router/react-navigation";import { useColorScheme } from "react-native";import { Stack } from "expo-router";
export default function Layout() {  const colorScheme = useColorScheme();  return (    <ThemeProvider value={colorScheme === "dark" ? DarkTheme : DefaultTheme}>      <Stack />    </ThemeProvider>  );}

If the app only uses a light or dark theme, you can directly pass DarkTheme or DefaultTheme to ThemeProvider without checking the color scheme.

tsx

import { ThemeProvider, DarkTheme } from "expo-router/react-navigation";import { Stack } from "expo-router";
export default function Layout() {  return (    <ThemeProvider value={DarkTheme}>      <Stack />    </ThemeProvider>  );}

Design engineering

Frameworks & libraries