React Navigation Native Bottom Tabs Navigator

https://reactnavigation.org/docs/native-bottom-tab-navigator
Admin
React Navigation Native Bottom Tabs Navigator is an experimental navigator that displays screens...
Tokens:4,553
Snippets:59
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Native Bottom Tabs package

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Install the required package using npm or yarn.

```bash
npm install @react-navigation/bottom-tabs
```

--------------------------------

### Implement Native Bottom Tab Navigator

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Examples of setting up the bottom tab navigator using both static and dynamic configuration patterns.

```js
import {
  createNativeBottomTabNavigator,
  createNativeBottomTabScreen,
} from '@react-navigation/bottom-tabs/unstable';

const MyTabs = createNativeBottomTabNavigator({
  screens: {
    Home: createNativeBottomTabScreen({
      screen: HomeScreen,
    }),
    Profile: createNativeBottomTabScreen({
      screen: ProfileScreen,
    }),
  },
});
```

```js
import { createNativeBottomTabNavigator } from '@react-navigation/bottom-tabs/unstable';

const Tab = createNativeBottomTabNavigator();

function MyTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen name="Home" component={HomeScreen} />
      <Tab.Screen name="Profile" component={ProfileScreen} />
    </Tab.Navigator>
  );
}
```

--------------------------------

### navigation.addListener('transitionStart', callback)

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Fired when the transition animation starts for the current screen.

```APIDOC
## Event: transitionStart

### Description
Fired when the transition animation starts for the current screen.

### Usage
```js
navigation.addListener('transitionStart', (e) => { /* custom logic */ });
```
```

--------------------------------

### Listen to transitionStart event

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Registers a listener for the transitionStart event to execute logic when a screen transition begins.

```js
React.useEffect(() => {
  const unsubscribe = navigation.addListener('transitionStart', (e) => {
    // Do something
  });

  return unsubscribe;
}, [navigation]);
```

--------------------------------

### navigation.jumpTo(name, params)

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Navigates to an existing screen in the tab navigator.

```APIDOC
## Method: jumpTo

### Description
Navigates to an existing screen in the tab navigator.

### Parameters
- **name** (string) - Required - Name of the route to jump to.
- **params** (object) - Optional - Screen params to use for the destination route.

### Example
```js
navigation.jumpTo('Profile', { owner: 'Michaś' });
```
```

--------------------------------

### Configure bottomAccessory

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Defines a function that returns a React element for the accessory view, receiving a placement parameter to handle different layout states.

```js
bottomAccessory: ({ placement }) => {
  return (
    <View style={{ padding: 16 }}>
      <Text>Placement: {placement}</Text>
    </View>
  );
};
```

--------------------------------

### Configure Platform-Specific Tab Icons

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Uses Platform.select to provide different icon configurations for iOS and Android.

```js
tabBarIcon: Platform.select({
  ios: {
    type: 'sfSymbol',
    name: 'heart',
  },
  android: {
    type: 'image',
    source: require('./path/to/icon.png'),
  },
});
```

--------------------------------

### Screen Options

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Configuration options available for screens within the Native Bottom Tab Navigator.

```APIDOC
## Screen Options

### title (string)
Generic title used as a fallback for `headerTitle` and `tabBarLabel`.

### tabBarSystemItem (string)
Uses iOS built-in tab bar items with standard styling. Supported values: 'bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'mostRecent', 'mostViewed', 'recents', 'search', 'topRated'.
```

--------------------------------

### Listen to transitionEnd event

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Registers a listener for the transitionEnd event to execute logic when a screen transition completes.

```js
React.useEffect(() => {
  const unsubscribe = navigation.addListener('transitionEnd', (e) => {
    // Do something
  });

  return unsubscribe;
}, [navigation]);
```

--------------------------------

### lazy

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Controls whether the screen should render only after the first time it is accessed.

```APIDOC
## lazy

### Description
Whether this screen should render only after the first time it's accessed.

### Type
boolean

### Default
false
```

--------------------------------

### Configure Dynamic Tab Icon

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Uses a function to return different icons based on the focused state. This is only supported on iOS.

```js
tabBarIcon: ({ focused }) => {
  return {
    type: 'sfSymbol',
    name: focused ? 'heart' : 'heart-outline',
  };
},
```

--------------------------------

### createNativeBottomTabNavigator

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Creates a native bottom tab navigator instance for managing screen navigation via tabs.

```APIDOC
## createNativeBottomTabNavigator

### Description
Creates a navigator that renders a native bottom tab bar. It supports both static configuration via an object and dynamic configuration via JSX components.

### Parameters
- **screens** (object) - Optional - Used in static configuration to define the screens within the navigator.

### Options
- **backBehavior** (string) - Controls the behavior when the back button or gesture is triggered. Supported values: 'firstRoute', 'initialRoute', 'order', 'history', 'fullHistory', 'none'.
```

--------------------------------

### navigation.addListener('transitionEnd', callback)

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Fired when the transition animation ends for the current screen.

```APIDOC
## Event: transitionEnd

### Description
Fired when the transition animation ends for the current screen.

### Usage
```js
navigation.addListener('transitionEnd', (e) => { /* custom logic */ });
```
```

--------------------------------

### Navigate with jumpTo

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Uses the jumpTo method to navigate to a specific route within the tab navigator with optional parameters.

```js
navigation.jumpTo('Profile', { owner: 'Michaś' });
```

--------------------------------

### Implement Search Tab on iOS 26+

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Configures a bottom tab navigator with a search system item and a stack navigator containing a search bar.

```javascript
import * as React from 'react';
import { Platform, View, Text, FlatList } from 'react-native';
import {
  createStaticNavigation,
  useNavigation,
} from '@react-navigation/native';
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
import { createNativeStackNavigator } from '@react-navigation/native-stack';

const DATA = [
  'Apple',
  'Banana',
  'Cherry',
  'Durian',
  'Elderberry',
  'Fig',
  'Grape',
];

function HomeScreen() {
  return (
    <View
      style={{
        flex: 1,
        alignItems: 'center',
        justifyContent: 'center',
      }}
    >
      <Text>Home Screen</Text>
    </View>
  );
}

function FruitsListScreen() {
  const [searchText, setSearchText] = React.useState('');

  const filteredData = DATA.filter((item) =>
    item.toLowerCase().includes(searchText.toLowerCase())
  );

  const navigation = useNavigation('FruitsList');

  React.useEffect(() => {
    navigation.setOptions({
      headerSearchBarOptions: {
        placeholder: 'Search fruits',
        onChange: (e) => {
          setSearchText(e.nativeEvent.text);
        },
      },
    });
  }, [navigation]);

  return (
    <FlatList
      data={filteredData}
      keyExtractor={(item) => item}
      renderItem={({ item }) => (
        <View
          style={{ padding: 16, borderBottomWidth: 1, borderColor: '#ccc' }}
        >
          <Text>{item}</Text>
        </View>
      )}
    />
  );
}

// codeblock-focus-start
const SearchStack = createNativeStackNavigator({
  screens: {
    FruitsList: {
      screen: FruitsListScreen,
      options: {
        title: 'Search',
        // highlight-start
        headerSearchBarOptions: {
          placeholder: 'Search fruits',
        },
        // highlight-end
      },
    },
  },
});

const HomeTabs = createBottomTabNavigator({
  screens: {
    Home: {
      screen: HomeScreen,
      options: {
        tabBarIcon: Platform.select({
          ios: {
            type: 'sfSymbol',
            name: 'house',
          },
          android: {
            type: 'materialSymbol',
            name: 'home',
          },
        }),
      },
    },
    Search: {
      // highlight-next-line
      screen: SearchStack,
      options: {
        // highlight-next-line
        tabBarSystemItem: 'search',
      },
    },
  },
});
// codeblock-focus-end

const Navigation = createStaticNavigation(HomeTabs);

export default function App() {
  return <Navigation />;
}
```

--------------------------------

### Configure Local Image Tab Icon

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Defines a local image as a tab icon. Ensure multiple screen densities are provided for proper scaling on iOS.

```js
tabBarIcon: {
  type: 'image',
  source: require('./path/to/icon.png'),
}
```

--------------------------------

### bottomAccessory

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Function that returns a React element to display as an accessory view. Supported on iOS 26 and above.

```APIDOC
## bottomAccessory

### Description
Function that returns a React element to display as an accessory view. Receives an options object with a 'placement' parameter ('regular' or 'inline').

### Type
(options: { placement: 'regular' | 'inline' }) => React.ReactNode
```

--------------------------------

### tabBarBadge

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Sets the text to show in a badge on the tab icon.

```APIDOC
## tabBarBadge

### Description
Text to show in a badge on the tab icon.

### Type
- string | number
```

--------------------------------

### Implement Search Tab on iOS

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Integrates a search bar within a stack navigator inside a bottom tab navigator using headerSearchBarOptions and tabBarSystemItem.

```js
const Stack = createNativeStackNavigator();

function SearchStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen
        name="FruitsList"
        component={FruitsListScreen}
        options={{
          title: 'Search',
          // highlight-start
          headerSearchBarOptions: {
            placeholder: 'Search fruits',
          },
          // highlight-end
        }}
      />
    </Stack.Navigator>
  );
}

const Tab = createBottomTabNavigator();

function HomeTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen
        name="Home"
        component={HomeScreen}
        options={{
          tabBarIcon: Platform.select({
            ios: {
              type: 'sfSymbol',
              name: 'house',
            },
            android: {
              type: 'materialSymbol',
              name: 'home',
            },
          }),
        }}
      />
      <Tab.Screen
        name="Search"
        // highlight-next-line
        component={SearchStack}
        options={{
          // highlight-next-line
          tabBarSystemItem: 'search',
        }}
      />
    </Tab.Navigator>
  );
}
```

--------------------------------

### Configure Drawable Resource Tab Icon

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Uses a drawable resource name for the tab icon on Android or an xcasset on iOS.

```js
tabBarIcon: {
  type: 'image',
  source: { uri: 'icon_name' },
}
```

--------------------------------

### Configure Tab Badge Style

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Sets the background and text color for the tab badge. Note that iOS only supports background color customization.

```js
tabBarBadgeStyle: {
  backgroundColor: 'yellow',
  color: 'black',
},
```

--------------------------------

### tabBarBadgeStyle

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Configures the style for the badge on the tab icon.

```APIDOC
## tabBarBadgeStyle

### Description
Style object for the badge. Supports `backgroundColor` and `color` (Android only for text color).
```

--------------------------------

### Configure Tab Label Style

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Applies custom font and size properties to tab labels using the tabBarLabelStyle option.

```js
tabBarLabelStyle: {
  fontSize: 16,
  fontFamily: 'Georgia',
  fontWeight: 300,
},
```

--------------------------------

### Listen to tabPress event

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Registers a listener for the tabPress event to execute custom logic when a tab is pressed.

```js
React.useEffect(() => {
  const unsubscribe = navigation.addListener('tabPress', (e) => {
    // Do something manually
    // ...
  });

  return unsubscribe;
}, [navigation]);
```

--------------------------------

### navigation.addListener('tabPress', callback)

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Fired when the user presses the tab button for the current screen. Provides hooks for custom behavior when a tab is interacted with.

```APIDOC
## Event: tabPress

### Description
Fired when the user presses the tab button for the current screen. If the tab is not focused, it focuses the tab; if already focused, it triggers scroll-to-top or pop-to-top actions if applicable.

### Usage
```js
navigation.addListener('tabPress', (e) => { /* custom logic */ });
```
```

--------------------------------

### tabBarIcon

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Configures the icon to display for the tab. Supports local images, drawable resources, xcassets, and SF Symbols (iOS).

```APIDOC
## tabBarIcon

### Description
Defines the icon to display for the tab. It can be an icon object or a function that returns an icon object based on the focused state.

### Configuration
- **type** (string) - 'image' or 'sfSymbol'
- **source** (object) - Required for 'image' type. Can be a local require or a URI object.
- **name** (string) - Required for 'sfSymbol' type. The name of the SF Symbol.
- **tinted** (boolean) - Optional. Controls whether the image is tinted. Defaults to true.
```

--------------------------------

### tabBarLabelStyle

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Style object for customizing the appearance of the tab label.

```APIDOC
### tabBarLabelStyle

- **Type**: object
- **Supported Properties**: fontFamily, fontSize, fontWeight, fontStyle
```

--------------------------------

### Configure Tinted Image Tab Icon

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Controls whether the image should be tinted with the active/inactive color. The tinted property is ignored on Android.

```js
tabBarIcon: {
  type: 'image',
  source: require('./path/to/icon.png'),
  tinted: false,
}
```

--------------------------------

### tabBarMinimizeBehavior

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Defines the minimize behavior for the tab bar. Supported on iOS 26 and above.

```APIDOC
## tabBarMinimizeBehavior

### Description
Controls how the tab bar minimizes. Supported values: 'auto', 'never', 'onScrollDown', 'onScrollUp'.

### Type
string

### Default
'auto'
```

--------------------------------

### Configure SF Symbol Tab Icon

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Sets an SF Symbol as the tab icon, supported on iOS.

```js
tabBarIcon: {
  type: 'sfSymbol',
  name: 'heart',
}
```

--------------------------------

### popToTopOnBlur

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Indicates whether a nested stack should be popped to the top when navigating away from the tab.

```APIDOC
## popToTopOnBlur

### Description
Boolean indicating whether any nested stack should be popped to the top of the stack when navigating away from this tab.

### Type
boolean

### Default
false
```

--------------------------------

### tabBarLabel

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Defines the title string displayed in the tab bar. This property overrides the label provided by tabBarSystemItem on iOS.

```APIDOC
### tabBarLabel

- **Type**: string
- **Description**: The title string of a tab displayed in the tab bar. If not provided, it falls back to the title or route name, or system values if tabBarSystemItem is set.
```

--------------------------------

### tabBarLabelVisibilityMode

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Controls the visibility mode for tab bar item labels on Android.

```APIDOC
### tabBarLabelVisibilityMode

- **Type**: 'auto' | 'selected' | 'labeled' | 'unlabeled'
- **Description**: Determines when labels are shown. Supported only on Android.
```

--------------------------------

### tabBarSelectionEnabled

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Determines whether a tab can be selected when tapped.

```APIDOC
## tabBarSelectionEnabled

### Description
Whether this tab can be selected. When false, tapping the tab won't select it, but custom behavior can be handled via the 'tabPress' event.

### Type
boolean

### Default
true
```

--------------------------------

### tabBarControllerMode

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Sets the display mode for the tab bar on iOS 18 and above.

```APIDOC
## tabBarControllerMode

### Description
The display mode for the tab bar.

### Supported Values
- auto: System sets mode based on content.
- tabBar: Displays content as a tab bar.
- tabSidebar: Displays content as a sidebar.
```

--------------------------------

### tabBarBlurEffect

Source: https://reactnavigation.org/docs/native-bottom-tab-navigator

Sets the blur effect applied to the tab bar on iOS 18 and lower.

```APIDOC
## tabBarBlurEffect

### Description
Blur effect applied to the tab bar. Defaults to 'systemDefault'.

### Supported Values
- none, systemDefault, extraLight, light, dark, regular, prominent, systemUltraThinMaterial, systemThinMaterial, systemMaterial, systemThickMaterial, systemChromeMaterial, and various light/dark variants.
```
Tokens:
Raw