https://github.com/zoontek/react-native-navigation-bar
React Native StatusBar long-lost twin: A component to control your Android app's navigation bar.
https://github.com/zoontek/react-native-navigation-bar
Last synced: 4 months ago
JSON representation
React Native StatusBar long-lost twin: A component to control your Android app's navigation bar.
- Host: GitHub
- URL: https://github.com/zoontek/react-native-navigation-bar
- Owner: zoontek
- License: mit
- Created: 2025-09-06T11:30:22.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-11-29T12:12:43.000Z (7 months ago)
- Last Synced: 2026-01-30T07:41:01.706Z (5 months ago)
- Language: TypeScript
- Homepage:
- Size: 487 KB
- Stars: 81
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# @zoontek/react-native-navigation-bar
React Native [`StatusBar`](https://reactnative.dev/docs/statusbar) long-lost twin: A component to control your Android app's navigation bar.
[](https://github.com/zoontek/react-native-navigation-bar/blob/main/LICENSE)
[](https://www.npmjs.com/package/@zoontek/react-native-navigation-bar)
[](https://www.npmjs.com/package/@zoontek/react-native-navigation-bar)
## Credits
This project has been built and is maintained thanks to the support from [Expo](https://expo.dev).
## Installation
```bash
$ 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).
```ruby
edgeToEdgeEnabled=true # 👈 set this to true
```
## Considerations
### Transparency
Compared to [`react-native-edge-to-edge`](https://github.com/zoontek/react-native-edge-to-edge), this library adopts React Native [`StatusBar`](https://reactnative.dev/docs/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:
```xml
<!-- … -->
<!-- enforce a contrasting navigation bar background (optional) -->
<item name="enforceNavigationBarContrast">true</item>
```
#### Expo
Add the library plugin to your app configuration file and [create a new build](https://docs.expo.dev/develop/development-builds/create-a-build) 👷:
Dynamic configuration (app.config.js, app.config.ts)
```ts
import type { ConfigContext, ExpoConfig } from "expo/config";
import navigationBar from "@zoontek/react-native-navigation-bar/expo"; // use `require` in app.config.js
export default ({ config }: ConfigContext): ExpoConfig => ({
plugins: [
navigationBar({
android: { enforceNavigationBarContrast: true },
}),
],
});
```
Static configuration (app.json)
```json
{
"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.
```tsx
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.pushStackEntry
Push a `NavigationBar` entry onto the stack. The return value should be passed to `popStackEntry` when complete.
```ts
const entry: NavigationBarProps = NavigationBar.pushStackEntry(
props /*: NavigationBarProps */,
);
```
#### NavigationBar.popStackEntry
Remove an existing `NavigationBar` stack entry from the stack.
```ts
NavigationBar.popStackEntry(entry /*: NavigationBarProps */);
```
#### NavigationBar.replaceStackEntry
Replace an existing `NavigationBar` stack entry with new props.
```ts
const entry: NavigationBarProps = NavigationBar.replaceStackEntry(
entry /*: NavigationBarProps */,
props /*: NavigationBarProps */,
);
```
#### NavigationBar.setBarStyle
Set the navigation bar style.
```ts
NavigationBar.setBarStyle(style /*: NavigationBarStyle */);
```
#### NavigationBar.setHidden
Show or hide the navigation bar.
```ts
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](https://github.com/zoontek/react-native-bootsplash).
#### The bar style behavior is erratic
There's currently [an open issue](https://issuetracker.google.com/issues/346386744) with the Android 15 emulator image regarding the navigation bar style when it is fully transparent. This issue does not occur on physical devices.