This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 53).

Expo Router native tabs

GitHub

Changelog

npm

An Expo Router submodule that provides native tabs layout.

Android

iOS

tvOS

Web

Native tabs are an experimental feature available in SDK 54 and above, and their API is subject to change.

expo-router/unstable-native-tabs is a submodule of expo-router and exports components to build tab layouts using platform-native system tabs.

See the Expo Router reference for more information about the file-based routing library for native and web app.

Installation

To use expo-router/unstable-native-tabs in your project, you need to install expo-router in your project. Follow the instructions from Expo Router's installation guide:

Install Expo Router

Learn how to install Expo Router in your project.

Configuration in app config

If you are using the default template to create a new project, expo-router's config plugin is already configured in your app config.

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": ["expo-router"]
  }
}

Usage

To learn how to use native tabs, with Expo Router, read the native tabs guide:

Native tabs

Learn how to use native tabs in your Expo Router app.

API

import { NativeTabs, Icon, Label, Badge } from 'expo-router/unstable-native-tabs';

Components

`Badge`

Android

iOS

tvOS

Web

Type: React.Element<BadgeProps>

BadgeProps

`children`

Android

iOS

tvOS

Web

Optional • Type: string

The text to display as the badge for the tab. If not provided, the badge will not be displayed.

`hidden`

Android

iOS

tvOS

Web

Optional • Type: boolean • Default: false

If true, the badge will be hidden.

`Icon`

Android

iOS

Type: React.Element<IconProps>

Renders an icon for the tab.

IconProps

`Label`

Android

iOS

tvOS

Web

Type: React.Element<LabelProps>

LabelProps

`children`

Android

iOS

tvOS

Web

Optional • Type: string

The text to display as the label for the tab.

`hidden`

Android

iOS

tvOS

Web

Optional • Type: boolean • Default: false

If true, the label will be hidden.

`NativeTabs`

Android

iOS

tvOS

Web

Type: React.Element<NativeTabsProps>

The component used to create native tabs layout.

Example

// In _layout file
import { NativeTabs } from 'expo-router/unstable-native-tabs';

export default function Layout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="home" />
      <NativeTabs.Trigger name="settings" />
    </NativeTabs>
  );
}

NativeTabsProps

`backBehavior`

Android

Optional • Literal type: string

The behavior when navigating back with the back button.

Acceptable values are: 'history' | 'none' | 'initialRoute'

`disableIndicator`

Android

Optional • Type: boolean

Disables the active indicator for the tab bar.

`minimizeBehavior`

iOS 26

Optional • Type: TabBarMinimizeBehavior • Default: automatic

https://developer.apple.com/documentation/uikit/uitabbarcontroller/tabbarminimizebehavior

Supported values:

none - The tab bar does not minimize.
onScrollUp - The tab bar minimizes when scrolling up, and expands when scrolling back down. Recommended if the scroll view content is aligned to the bottom.
onScrollDown - The tab bar minimizes when scrolling down, and expands when scrolling back up.
automatic - Resolves to the system default minimize behavior.

`style`

Android

iOS

tvOS

Web

Optional • Type: NativeTabsStyleType

Inherited Props

PropsWithChildren

`NativeTabTrigger`

Android

iOS

tvOS

Web

Type: React.Element<NativeTabTriggerProps>

The component used to customize the native tab options both in the _layout file and from the tab screen.

When used in the _layout file, you need to provide a name prop. When used in the tab screen, the name prop takes no effect.

Example

// In _layout file
import { NativeTabs } from 'expo-router/unstable-native-tabs';

export default function Layout() {
  return (
    <NativeTabs>
      <NativeTabs.Trigger name="home" />
      <NativeTabs.Trigger name="settings" />
    </NativeTabs>
  );
}

Example

// In a tab screen
import { NativeTabs } from 'expo-router/unstable-native-tabs';

export default function HomeScreen() {
  return (
    <View>
      <NativeTabs.Trigger>
        <Label>Home</Label>
      </NativeTabs.Trigger>
      <Text>This is home screen!</Text>
    </View>
  );
}

**Note:** You can use the alias `NativeTabs.Trigger` for this component.

NativeTabTriggerProps

`children`

Android

iOS

tvOS

Web

Optional • Type: ReactNode

The children of the trigger.

Use Icon, Label, and Badge components to customize the tab.

`disablePopToTop`

iOS

Optional • Type: boolean • Default: false

If true, the tab will not pop stack to the root when selected again.

`disableScrollToTop`

iOS

Optional • Type: boolean • Default: false

If true, the tab will not scroll to the top when selected again.

`hidden`

Android

iOS

tvOS

Web

Optional • Type: boolean

If true, the tab will be hidden from the tab bar.

`name`

Android

iOS

tvOS

Web

Optional • Type: string

The name of the route.

This is required when used inside a Layout component.

When used in a route it has no effect.

`options`

Android

iOS

tvOS

Web

Optional • Type: NativeTabOptions

The options for the trigger.

Use Icon, Label, and Badge components as children to customize the tab, rather then raw options.

Interfaces

`NamedIconCombination`

Android

iOS

tvOS

Web

Property	Type	Description
drawable(optional)	`string`	Only for: Android The name of the drawable resource to use as an icon.
selectedSf(optional)	`SFSymbols6_0`	Only for: iOS The name of the SF Symbol to use as an icon when the tab is selected.
selectedSrc(optional)	`undefined`	-
sf(optional)	`SFSymbols6_0`	Only for: iOS The name of the SF Symbol to use as an icon.
src(optional)	`undefined`	-

`NativeTabsActiveStyleType`

Android

iOS

tvOS

Web

Property	Type	Description
color(optional)	`ColorValue`	Only for: Android Web -
fontSize(optional)	`number`	Only for: Android Web -
iconColor(optional)	`ColorValue`	Only for: Android -
indicatorColor(optional)	`ColorValue`	Only for: Android Web -

`NativeTabsStyleType`

Android

iOS

tvOS

Web

Property	Type	Description
&:active(optional)	`NativeTabsActiveStyleType`	Only for: Android Web -
backgroundColor(optional)	`ColorValue`	-
badgeBackgroundColor(optional)	`ColorValue`	-
badgeTextColor(optional)	`ColorValue`	Only for: Android Web -
blurEffect(optional)	`BottomTabsScreenBlurEffect`	Only for: iOS -
color(optional)	`ColorValue`	-
fontFamily(optional)	`string`	-
fontSize(optional)	`number`	-
fontStyle(optional)	`'italic' \| 'normal'`	-
fontWeight(optional)	`NumericFontWeight \| '100' \| '200' \| '300' \| '400' \| '500' \| '600' \| '700' \| '800' \| '900'`	-
iconColor(optional)	`ColorValue`	Only for: Android iOS tvOS -
labelVisibilityMode(optional)	`TabBarItemLabelVisibilityMode`	Only for: Android -
rippleColor(optional)	`ColorValue`	Only for: Android -
tintColor(optional)	`ColorValue`	Only for: Android iOS Web -
titlePositionAdjustment(optional)	`{ horizontal: number, vertical: number }`	Only for: iOS - See: Apple documentation

`SourceIconCombination`

Android

iOS

tvOS

Web

Property	Type	Description
drawable(optional)	`string`	Only for: Android The name of the drawable resource to use as an icon.
selectedSf(optional)	`undefined`	-
selectedSrc(optional)	`ImageSourcePropType`	Only for: iOS The image source to use as an icon when the tab is selected.
sf(optional)	`undefined`	-
src(optional)	`ImageSourcePropType`	Only for: iOS The image source to use as an icon.

Types

`NativeTabOptions`

Android

iOS

tvOS

Web

Property	Type	Description
icon(optional)	`SfSymbolOrImageSource & { drawable: string }`	Only for: Android iOS The icon to display in the tab bar.
selectedIcon(optional)	`SfSymbolOrImageSource`	Only for: iOS The icon to display when the tab is selected.

`SfSymbolOrImageSource`

Android

iOS

tvOS

Web

Type: object shaped as below:

Property	Type	Description
sf(optional)	`SFSymbol`	Only for: iOS The name of the SF Symbol to use as an icon.

Or object shaped as below:

Property	Type	Description
src(optional)	`ImageSourcePropType`	Only for: iOS The image source to use as an icon.