@zoontek/react-native-navigation-bar

React Native StatusBar long-lost twin: A component to control your Android app's navigation bar.

Credits

This project has been built and is maintained thanks to the support from Expo.

Installation

$ npm i -S @zoontek/react-native-navigation-bar
# --- or ---
$ yarn add @zoontek/react-native-navigation-bar

[!IMPORTANT] This library requires React Native 0.81+ or Expo 54+ with edge-to-edge enabled. To turn it on, set edgeToEdgeEnabled to true in your project's gradle.properties file (this step is not required for Expo, as it is enabled by default).

edgeToEdgeEnabled=true # 👈 set this to true

Considerations

Transparency

Compared to react-native-edge-to-edge, this library adopts React Native StatusBar API and its defaults: the navigation bar is transparent with a light-content bar style. To enforce a contrasting (semi-opaque) button navigation bar, set the enforceNavigationBarContrast option to true.

React Native

Edit your android/app/src/main/res/values/styles.xml file to add the enforceNavigationBarContrast attribute:

<resources>
  <style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
    <!-- … -->
    <!-- enforce a contrasting navigation bar background (optional) -->
    <item name="enforceNavigationBarContrast">true</item>
  </style>
</resources>

Expo

Add the library plugin to your app.json configuration file and create a new build 👷:

{
  "expo": {
    "plugins": [
      [
        "@zoontek/react-native-navigation-bar",
        { "android": { "enforceNavigationBarContrast": true } }
      ]
    ]
  }
}

API

NavigationBar

A React component to control the Android button navigation bar (with back / home / recents buttons).

[!NOTE] This component has no effect on other platforms or when gesture navigation is used.

import { NavigationBar } from "@zoontek/react-native-navigation-bar";

type NavigationBarStyle = "default" | "light-content" | "dark-content";

type NavigationBarProps = {
  barStyle?: NavigationBarStyle; // set the color of the navigation bar content
  hidden?: boolean; // hide the navigation bar
};

const App = () => (
  <>
    <NavigationBar barStyle="light-content" />
    {/* … */}
  </>
);

NavigationBar.pushStackEntry

Push a NavigationBar entry onto the stack. The return value should be passed to popStackEntry when complete.

const entry: NavigationBarProps = NavigationBar.pushStackEntry(
  props /*: NavigationBarProps */,
);

NavigationBar.popStackEntry

Remove an existing NavigationBar stack entry from the stack.

NavigationBar.popStackEntry(entry /*: NavigationBarProps */);

NavigationBar.replaceStackEntry

Replace an existing NavigationBar stack entry with new props.

const entry: NavigationBarProps = NavigationBar.replaceStackEntry(
  entry /*: NavigationBarProps */,
  props /*: NavigationBarProps */,
);

NavigationBar.setBarStyle

Set the navigation bar style.

NavigationBar.setBarStyle(style /*: NavigationBarStyle */);

NavigationBar.setHidden

Show or hide the navigation bar.

NavigationBar.setHidden(style /*: boolean */);

Troubleshooting 🤔

The bar style blinks at app start

Since the navigation bar is set at runtime rather than through themes, you may notice a brief style change at startup. This can be avoided by adding a splash screen.

The bar style behavior is erratic

There's currently an open issue with the Android 15 emulator image regarding the navigation bar style when it is fully transparent. This issue does not occur on physical devices.