Expo NavigationBar

A library that provides access to various interactions with the native navigation bar on Android.

Android

Included in Expo Go

Recommended version:

~5.0.10

expo-navigation-bar enables you to modify and observe the native navigation bar on Android devices. Due to some Android platform restrictions, parts of this API overlap with the expo-status-bar API.

Properties are named after style properties; visibility, position, backgroundColor, borderColor, and so on.

The APIs in this package have no impact when "Gesture Navigation" is enabled on the Android device. There is currently no native Android API to detect if "Gesture Navigation" is enabled or not.

Installation

Terminal

- npx expo install expo-navigation-bar

If you are installing this in an existing React Native app, make sure to install expo in your project.

Configuration in app config

You can configure expo-navigation-bar using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-navigation-bar",
        {
          "backgroundColor": "#0f172a",
          "barStyle": "light",
          "borderColor": "#1f2937",
          "visibility": "visible",
          "behavior": "inset-swipe",
          "position": "relative"
        }
      ]
    ]
  }
}

Configurable properties

Name	Default	Description
`backgroundColor`	`undefined`	Sets the navigation bar background color. Accepts color string supported by React Native. For example, `"#0f172a"`.
`barStyle`	`undefined`	Controls whether Android renders light or dark navigation bar buttons. Accepts `light` and `dark` as values.
`borderColor`	`undefined`	Sets the divider color above the navigation bar.
`visibility`	`undefined`	Determines whether the navigation bar starts visible or hidden. Accepts `visible` to show the bar immediately and `hidden` to hide it until the user reveals it with a system gesture.
`behavior`	`undefined`	Controls how hidden system bars behave when revealed. Accepts `overlay-swipe`, `inset-swipe`, or `inset-touch` as values.
`position`	`undefined`	Sets whether your layout is inset for the navigation bar. Accepts `relative` to keep the navigation bar outside the content and `absolute` to draw the content edge-to-edge under the bar.
`legacyVisible`	`undefined`	Legacy equivalent of `androidNavigationBar.visible`. Accepts `leanback`, `immersive`, or `sticky-immersive` as values.

Are you using this library in an existing React Native app?

If you're not using Continuous Native Generation (CNG) or you're using a native android project manually, then you need to add the following configuration to your native project:

To apply backgroundColor to the navigation bar, add navigationBarColor to android/app/src/main/res/values/colors.xml:

<resources>
  <!-- ... -->
  <color name="navigationBarColor">#0f172a</color>
</resources>

Then, apply android:navigationBarColor to android/app/src/main/res/values/styles.xml:

<style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
  <!-- ... -->
  <item name="android:navigationBarColor">@color/navigationBarColor</item>
</style>

To apply borderColor, visibility, position, and behavior to the navigation bar, add expo_navigation_bar_border_color, expo_navigation_bar_visibility, expo_navigation_bar_position, and expo_navigation_bar_behavior to android/app/src/main/res/values/strings.xml:

<resources>
  <!-- ... -->
  <!-- For `expo_navigation_bar_border_color`, convert the color string to a 32-bit integer. -->
  <string name="expo_navigation_bar_border_color"
  translatable="false">-14735049</string>
  <string name="expo_navigation_bar_visibility" translatable="false">visible</string>
  <string name="expo_navigation_bar_position" translatable="false">relative</string>
  <string name="expo_navigation_bar_behavior" translatable="false">inset-swipe</string>
</resources>

To apply legacyVisible to the navigation bar, add expo_navigation_bar_legacy_visible to android/app/src/main/res/values/strings.xml:

<resources>
  <!-- ... -->
  <string name="expo_navigation_bar_legacy_visible" translatable="false">immersive</string>
</resources>

API

import * as NavigationBar from 'expo-navigation-bar';

Component

`NavigationBar`

Android

Type: React.Element<NavigationBarProps>

A component that allows you to configure your navigation bar declaratively.

You will likely have multiple NavigationBar components mounted in the same app at the same time. For example, if you have multiple screens in your app, you may end up using one per screen. The props of each NavigationBar component will be merged in the order that they were mounted.

NavigationBarProps

`hidden`

Android

Optional • Type: boolean

If the navigation bar is hidden.

`style`

Android

Optional • Type: NavigationBarStyle • Default: 'auto'

Sets the color of the navigation bar buttons. Default value is "auto" which picks the appropriate value according to the active color scheme, eg: if your app is dark mode, the style will be "light".

This will have an effect when the following conditions are met:

The device navigation bar is using buttons.

The enforceContrast option of the expo-navigation-bar plugin is set to false.

Due to a bug in the Android 15 emulator this function may have no effect. Try a physical device or an emulator with a different version of Android.

Component Methods

`setHidden(hidden)`

Android

Parameter	Type	Description
hidden	`boolean`	If the navigation bar should be hidden.

Set the navigation bar's visibility.

Returns:

void

Example

NavigationBar.setHidden(true);

`setStyle(style)`

Android

Parameter	Type	Description
style	`NavigationBarStyle`	The color of the navigation bar buttons.

Sets the style of the navigation bar.

This will have an effect when the following conditions are met:

The device navigation bar is using buttons.

The enforceContrast option of the expo-navigation-bar plugin is set to false.

Due to a bug in the Android 15 emulator this function may have no effect. Try a physical device or an emulator with a different version of Android.

Returns:

void

Example

NavigationBar.setStyle("dark");

Hooks

Deprecated: This will be removed in a future release.

`useVisibility()`

Android

React hook that statefully updates with the visibility of the system navigation bar.

Returns:

NavigationBarVisibility | null

Visibility of the navigation bar, null during async initialization.

Methods

Deprecated: This will be removed in a future release.

`NavigationBar.getVisibilityAsync()`

Android

Get the navigation bar's visibility.

Returns:

Promise<NavigationBarVisibility>

Navigation bar's current visibility status. Returns hidden on unsupported platforms (iOS, web).

Deprecated: Use NavigationBar.setStyle instead. This will be removed in a future release.

`NavigationBar.setStyle(style)`

Android

Parameter	Type	Description
style	`NavigationBarStyle`	The color of the navigation bar buttons.

Returns:

void

Deprecated: Use NavigationBar.setHidden instead. This will be removed in a future release.

`NavigationBar.setVisibilityAsync(visibility)`

Android

Parameter	Type	Description
visibility	`NavigationBarVisibility`	Based on CSS visibility property.

Set the navigation bar's visibility.

Returns:

Promise<void>

Event Subscriptions

Deprecated: This will be removed in a future release.

`NavigationBar.addVisibilityListener(listener)`

Android

Parameter	Type
listener	`(event: NavigationBarVisibilityEvent) => void`

Observe changes to the system navigation bar. Due to platform constraints, this callback will also be triggered when the status bar visibility changes.

Returns:

EventSubscription

Types

`NavigationBarStyle`

Android

Literal Type: string

Navigation bar style.

auto will automatically adjust based on the current theme.
light a light navigation bar with dark content.
dark a dark navigation bar with light content.
inverted the bar colors are inverted in relation to the current theme.

Acceptable values are: 'auto' | 'inverted' | 'light' | 'dark'

Deprecated: This will be removed in a future release.

`NavigationBarVisibility`

Android

Literal Type: string

Visibility of the navigation bar.

Acceptable values are: 'visible' | 'hidden'

Deprecated: This will be removed in a future release.

`NavigationBarVisibilityEvent`

Android

Current system UI visibility state. Due to platform constraints, this will return when the status bar visibility changes as well as the navigation bar.

Property	Type	Description
rawVisibility	`number`	Native Android system UI visibility state, returned from the native Android `setOnSystemUiVisibilityChangeListener` API.
visibility	`NavigationBarVisibility`	Current navigation bar visibility.