@capawesome/capacitor-navigation-bar

Capacitor plugin to set the background color and button style of the navigation bar.

Features

We are proud to offer one of the most complete and feature-rich Capacitor plugins for navigation bar customization. Here are some of the key features:

• 🎨 Background color: Set the navigation bar background to any hex color or fully transparent.
• 🔘 Button style: Choose dark or light navigation bar buttons, or follow the system appearance.
• ➖ Divider color: Customize the navigation bar divider color on Android 9+.
• 👁️ Visibility: Hide or show the navigation bar on demand.
• ⚙️ Configuration: Apply defaults at app launch via the Capacitor configuration.
• 🔁 Up-to-date: Always supports the latest Capacitor version.
• ⭐️ Support: Priority support from the Capawesome Team.
• ✨ Handcrafted: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just open an issue and we'll take a look!

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Compatibility

| Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 8.x.x | >=8.x.x | Active support |

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-navigation-bar` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands:

npm install @capawesome/capacitor-navigation-bar
npx cap sync

Configuration

| Prop | Type | Description | Since | | ------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | color | string | The hexadecimal color to set as the background color of the navigation bar. Use 'transparent' to make the navigation bar transparent. Only available on Android. | 8.0.0 | | dividerColor | string | The hexadecimal color to set as the color of the navigation bar divider. Use 'transparent' to hide the divider. Only available on Android (API level 28+). | 8.0.0 | | style | 'DARK' | 'LIGHT' | 'DEFAULT' | The style of the navigation bar buttons. Only available on Android. | 8.0.0 |

Examples

In capacitor.config.json:

{
  "plugins": {
    "NavigationBar": {
      "color": "#ffffff",
      "dividerColor": "#d9d9d9",
      "style": "LIGHT"
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capawesome/capacitor-navigation-bar" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    NavigationBar: {
      color: "#ffffff",
      dividerColor: "#d9d9d9",
      style: "LIGHT",
    },
  },
};

export default config;

Usage

import { NavigationBar, Style } from '@capawesome/capacitor-navigation-bar';

const setColor = async () => {
  await NavigationBar.setColor({ color: '#ffffff' });
};

const setStyle = async () => {
  await NavigationBar.setStyle({ style: Style.Light });
};

const getColor = async () => {
  const { color } = await NavigationBar.getColor();
  return color;
};

const getStyle = async () => {
  const { style } = await NavigationBar.getStyle();
  return style;
};

const hide = async () => {
  await NavigationBar.hide();
};

const show = async () => {
  await NavigationBar.show();
};

API

• getColor()
• getStyle()
• hide()
• setColor(...)
• setStyle(...)
• show()
• Interfaces
• Enums

getColor()

getColor() => Promise<GetColorResult>

Get the current background color of the navigation bar.

Only available on Android.

Returns: Promise<GetColorResult>

Since: 8.0.0

getStyle()

getStyle() => Promise<GetStyleResult>

Get the current style of the navigation bar buttons.

Only available on Android.

Returns: Promise<GetStyleResult>

Since: 8.0.0

hide()

hide() => Promise<void>

Hide the navigation bar.

Only available on Android.

Since: 8.0.0

setColor(...)

setColor(options: SetColorOptions) => Promise<void>

Set the background color of the navigation bar.

Only available on Android.

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | SetColorOptions |

Since: 8.0.0

setStyle(...)

setStyle(options: SetStyleOptions) => Promise<void>

Set the style of the navigation bar buttons.

Only available on Android.

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | SetStyleOptions |

Since: 8.0.0

show()

show() => Promise<void>

Show the navigation bar.

Only available on Android.

Since: 8.0.0

Interfaces

GetColorResult

| Prop | Type | Description | Since | | ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------- | ----- | | color | string | The hexadecimal color of the navigation bar, or 'transparent' if the navigation bar is fully transparent. | 8.0.0 |

GetStyleResult

| Prop | Type | Description | Since | | ----------- | --------------------------------------- | ---------------------------------------- | ----- | | style | Style | The style of the navigation bar buttons. | 8.0.0 |

SetColorOptions

| Prop | Type | Description | Since | | ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | color | string | The hexadecimal color to set as the background color of the navigation bar. Use 'transparent' to make the navigation bar transparent. | 8.0.0 | | dividerColor | string | The hexadecimal color to set as the color of the navigation bar divider. Use 'transparent' to hide the divider. Only available on Android (API level 28+). | 8.0.0 |

SetStyleOptions

| Prop | Type | Description | Since | | ----------- | --------------------------------------- | ---------------------------------------- | ----- | | style | Style | The style of the navigation bar buttons. | 8.0.0 |

Enums

Style

| Members | Value | Description | Since | | ------------- | ---------------------- | -------------------------------------------- | ----- | | Dark | 'DARK' | Light icons on a dark background. | 8.0.0 | | Default | 'DEFAULT' | Resolved from the current device appearance. | 8.0.0 | | Light | 'LIGHT' | Dark icons on a light background. | 8.0.0 |

FAQ

Why are the setColor and setStyle methods not working on Android 15+?

Starting with Android 15, the system enforces edge-to-edge display by default. In this mode the navigation bar is fully transparent and Window.setNavigationBarColor becomes a no-op, so setting the color through this plugin has no visible effect. If your app targets Android 15+ and you want to color the navigation bar area, use the @capawesome/capacitor-android-edge-to-edge-support plugin, which paints an overlay behind the navigation bar.

Why is this plugin not available on iOS?

iOS does not have a system navigation bar that can be customized in the same way as on Android. All methods of this plugin are therefore unimplemented on iOS and reject with an error.

Changelog

See CHANGELOG.md.

License

See LICENSE.