This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 53).
An Expo Router submodule that provides native tabs layout.
Native tabs is an experimental feature available in SDK 54 and above, and its 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:
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
{ "expo": { "plugins": ["expo-router"] } }
Usage
To learn how to use native tabs, with Expo Router, read the native tabs guide:
Learn how to use native tabs in your Expo Router app.
API
import { NativeTabs, Icon, Label, Badge, VectorIcon } from 'expo-router/unstable-native-tabs';
Components
Type: React.Element<BadgeProps>
string
The text to display as the badge for the tab. If not provided, the badge will not be displayed.
hidden
boolean
• Default: false
If true, the badge will be hidden.
ColorValue
Type: React.Element<LabelProps>
hidden
boolean
• Default: false
If true, the label will be hidden.
NativeTabsLabelStyle
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> ); }
string
The behavior when navigating back with the back button.
Acceptable values are: 'history'
| 'none'
| 'initialRoute'
union
The background color of the tab bar.
Acceptable values are: null
| ColorValue
ColorValue
The background color of every badge in the tab bar.
string
The blur effect applied to the tab bar.
Acceptable values are: 'none'
| 'systemDefault'
| 'extraLight'
| 'light'
| 'dark'
| 'regular'
| 'prominent'
| 'systemUltraThinMaterial'
| 'systemThinMaterial'
| 'systemMaterial'
| 'systemThickMaterial'
| 'systemChromeMaterial'
| 'systemUltraThinMaterialLight'
| 'systemThinMaterialLight'
| 'systemMaterialLight'
| 'systemThickMaterialLight'
| 'systemChromeMaterialLight'
| 'systemUltraThinMaterialDark'
| 'systemThinMaterialDark'
| 'systemMaterialDark'
| 'systemThickMaterialDark'
| 'systemChromeMaterialDark'
boolean
When set to true
, the tab bar will not become transparent when scrolled to the edge.
NativeTabsLabelStyle
The style of the every tab label in the tab bar.
string
The visibility mode of the tab item label.
Acceptable values are: 'auto'
| 'selected'
| 'labeled'
| 'unlabeled'
string
• Default: automatic
Specifies the minimize behavior for the tab bar.
Available starting from iOS 26.
The following values are currently supported:
automatic
- resolves to the system default minimize behaviornever
- the tab bar does not minimizeonScrollDown
- the tab bar minimizes when scrolling down and expands when scrolling back uponScrollUp
- the tab bar minimizes when scrolling up and expands when scrolling back down
See: The supported values correspond to the official UIKit documentation.
Acceptable values are: 'automatic'
| 'never'
| 'onScrollDown'
| 'onScrollUp'
ColorValue
The color of the ripple effect when the tab is pressed.
ColorValue
The tint color of the tab icon.
Can be overridden by icon color and label color for each tab individually.
{
horizontal: number,
vertical: number
}
See: Apple documentation
Type: React.Element<NativeTabsTriggerTabBarProps>
The component used to customize the style of the tab bar, when given trigger is selected.
Prefer this to global changes of tab bar styles, directly in the page.
Note: You can use the alias
NativeTabs.Trigger.TabBar
for this component.
Example
<NativeTabs backgroundColor="black" > <NativeTabs.Trigger name="page"> <NativeTabs.Trigger.TabBar backgroundColor="white" /> <Label>Page</Label> </NativeTabs.Trigger> </NativeTabs>
ColorValue
The background color of the tab bar, when the tab is selected
ColorValue
The background color of every badge in the tab bar.
string
The blur effect applied to the tab bar, when the tab is selected
Acceptable values are: 'none'
| 'systemDefault'
| 'extraLight'
| 'light'
| 'dark'
| 'regular'
| 'prominent'
| 'systemUltraThinMaterial'
| 'systemThinMaterial'
| 'systemMaterial'
| 'systemThickMaterial'
| 'systemChromeMaterial'
| 'systemUltraThinMaterialLight'
| 'systemThinMaterialLight'
| 'systemMaterialLight'
| 'systemThickMaterialLight'
| 'systemChromeMaterialLight'
| 'systemUltraThinMaterialDark'
| 'systemThinMaterialDark'
| 'systemMaterialDark'
| 'systemThickMaterialDark'
| 'systemChromeMaterialDark'
boolean
When set to true
, the tab bar will not become transparent when scrolled to the edge.
NativeTabsLabelStyle
The style of the every tab label in the tab bar.
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.
ReactNode
The children of the trigger.
Use Icon
, Label
, and Badge
components to customize the tab.
boolean
• Default: false
If true, the tab will not pop stack to the root when selected again.
boolean
• Default: false
If true, the tab will not scroll to the top when selected again.
hidden
boolean
If true, the tab will be hidden from the tab bar.
string
The name of the route.
This is required when used inside a Layout component.
When used in a route it has no effect.
NativeTabOptions
The options for the trigger.
Use Icon
, Label
, and Badge
components as children to customize the tab, rather then raw options.
string
System-provided tab bar item with predefined icon and title
Uses Apple's built-in tab bar items (e.g., bookmarks, contacts, downloads) with
standard iOS styling and localized titles. Custom icon
or selectedIcon
properties will override the system icon, but the system-defined title cannot
be customized.
Acceptable values are: 'search'
| 'history'
| 'bookmarks'
| 'contacts'
| 'downloads'
| 'favorites'
| 'featured'
| 'more'
| 'mostRecent'
| 'mostViewed'
| 'recents'
| 'topRated'
Type: React.Element<VectorIconProps<NameT>>
Helper component which can be used to load vector icons for NativeTabs
.
Example
import { NativeTabs, VectorIcon } from 'expo-router'; import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons'; export default Layout(){ return ( <NativeTabs> <NativeTabs.Trigger name="index"> <Icon src={<VectorIcon family={MaterialCommunityIcons} name="home" />} /> </NativeTabs.Trigger> </NativeTabs> ); }
{
getImageSource: (name: NameT, size: number, color: ColorValue) => Promise<ImageSourcePropType>
}
The family of the vector icon.
Example
import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons';
Interfaces
Property | Type | Description |
---|---|---|
drawable(optional) | string | Only for: Android The name of the drawable resource to use as an icon. |
sf(optional) | SFSymbols6_0 | {
default: SFSymbols6_0 | undefined,
selected: SFSymbols6_0
} | Only for: iOS The name of the SF Symbol to use as an icon. The value can be provided in two ways:
Example
Example
|
src(optional) | undefined | - |
Extends: DefaultRouterOptions
Property | Type | Description |
---|---|---|
backgroundColor(optional) | ColorValue | The color of the background when the tab is selected. |
badgeBackgroundColor(optional) | ColorValue | The color of all the badges when the tab is selected. |
badgeTextColor(optional) | ColorValue | Only for: Android Web The color of the badge text. |
badgeValue(optional) | string | Only for: Android iOS Specifies content of tab bar item badge. On Android, the value is interpreted in the following order:
On iOS, badge is displayed as regular string. |
blurEffect(optional) | 'none' | 'systemDefault' | 'extraLight' | 'light' | 'dark' | 'regular' | 'prominent' | 'systemUltraThinMaterial' | 'systemThinMaterial' | 'systemMaterial' | 'systemThickMaterial' | 'systemChromeMaterial' | 'systemUltraThinMaterialLight' | 'systemThinMaterialLight' | 'systemMaterialLight' | 'systemThickMaterialLight' | 'systemChromeMaterialLight' | 'systemUltraThinMaterialDark' | 'systemThinMaterialDark' | 'systemMaterialDark' | 'systemThickMaterialDark' | 'systemChromeMaterialDark' | Only for: iOS The blur effect to apply when the tab is selected. |
disableTransparentOnScrollEdge(optional) | boolean | Only for: iOS When set to |
icon(optional) | SymbolOrImageSource | Only for: Android iOS The icon to display in the tab bar. |
iconColor(optional) | ColorValue | The color of the icon when the tab is selected. On iOS 26+ you can change the icon color in the scroll edge state. |
indicatorColor(optional) | ColorValue | Only for: Android Web The color of the tab indicator. |
labelStyle(optional) | NativeTabsLabelStyle | The style of all the tab labels, when the tab is selected |
role(optional) | 'search' | 'history' | 'bookmarks' | 'contacts' | 'downloads' | 'favorites' | 'featured' | 'more' | 'mostRecent' | 'mostViewed' | 'recents' | 'topRated' | Only for: iOS System-provided tab bar item with predefined icon and title Uses Apple's built-in tab bar items (e.g., bookmarks, contacts, downloads) with
standard iOS styling and localized titles. Custom |
selectedBadgeBackgroundColor(optional) | ColorValue | The color of the badge when the tab is selected. |
selectedIcon(optional) | SymbolOrImageSource | Only for: iOS The icon to display when the tab is selected. |
selectedIconColor(optional) | ColorValue | The color of the icon when the tab is selected. |
selectedLabelStyle(optional) | NativeTabsLabelStyle | The style of the tab label when the tab is selected. |
selectedTitlePositionAdjustment(optional) | {
horizontal: number,
vertical: number
} | Only for: iOS The position adjustment for the label when the tab is selected. |
title(optional) | string | Only for: Android iOS Title of the tab screen, displayed in the tab bar item. |
titlePositionAdjustment(optional) | {
horizontal: number,
vertical: number
} | Only for: iOS The position adjustment for all the labels when the tab is selected. |
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 |
Property | Type | Description |
---|---|---|
color(optional) | ColorValue | The color of the tab label. |
fontFamily(optional) | string | The font family of the tab label. |
fontSize(optional) | number | The font size of the tab label. |
fontStyle(optional) | 'italic' | 'normal' | The font style of the tab label. |
fontWeight(optional) | NumericFontWeight | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | The font weight of the tab label. |
Property | Type | Description |
---|---|---|
drawable(optional) | undefined | - |
sf(optional) | undefined | - |
src(optional) | ReactElement | ImageSourcePropType | {
default: ReactElement<unknown, string | JSXElementConstructor<any>> | ImageSourcePropType | undefined,
selected: ReactElement<unknown, string | JSXElementConstructor<any>> | ImageSourcePropType
} | Only for: Android iOS The image source to use as an icon. The value can be provided in two ways:
Example
Example
|
Types
Type: object
shaped as below:
Property | Type | Description |
---|---|---|
drawable(optional) | string | Only for: Android The name of the drawable resource to use as an icon. |
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 | Promise<ImageSourcePropType> | The image source to use as an icon. |