Expo Router native tabs

GitHub

Changelog

npm

An Expo Router submodule that provides native tabs layout.

Android

iOS

tvOS

Web

Bundled version:

~6.0.0-beta.1

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`

Type: React.Element<BadgeProps>

BadgeProps

`children`

Optional • Type: string

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

`hidden`

Optional • Type: boolean • Default: false

If true, the badge will be hidden.

`Icon`

Only for:

Android

iOS

Type: React.Element<IconProps>

Renders an icon for the tab.

IconProps

`Label`

Type: React.Element<LabelProps>

LabelProps

`children`

Optional • Type: string

The text to display as the label for the tab.

`hidden`

Optional • Type: boolean • Default: false

If true, the label will be hidden.

`NativeTabs`

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`

Only for:

Android

Optional • Literal type: string

The behavior when navigating back with the back button.

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

`disableIndicator`

Only for:

Android

Optional • Type: boolean

Disables the active indicator for the tab bar.

`minimizeBehavior`

Only for:

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`

Optional • Type: NativeTabsStyleType

Inherited Props

PropsWithChildren

`NativeTabTrigger`

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`

Optional • Type: ReactNode

The children of the trigger.

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

`disablePopToTop`

Only for:

iOS

Optional • Type: boolean • Default: false

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

`disableScrollToTop`

Only for:

iOS

Optional • Type: boolean • Default: false

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

`hidden`

Optional • Type: boolean

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

`name`

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`

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`

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`

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`

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`

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`

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`

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.