Capacitor Navigation Bar Plugin

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

Features

The Capacitor Navigation Bar plugin offers one of the most complete solutions for customizing the Android navigation bar in Capacitor apps. 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.
• 🤝 Compatibility: Works alongside the Android Dark Mode Support, Android Edge-to-Edge Support and Home Indicator plugins.
• 🔁 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!

Use Cases

The Navigation Bar plugin is typically used to make the Android system navigation bar blend in with the app's design, for example:

• Brand theming: Set the navigation bar background to your brand color so it matches the rest of your app.
• Dark mode support: Switch the navigation bar color and button style when the user toggles between light and dark themes.
• Immersive experiences: Hide the navigation bar for fullscreen content such as videos or games and show it again afterwards.
• Consistent app launch: Apply a default color, divider color, and button style at app launch via the Capacitor configuration.

Compatibility

Guides

• Capacitor Edge-to-Edge & Safe Areas: The Complete Guide

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

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

The following examples show how to set the navigation bar color and button style, read the current color and style, and hide and show the navigation bar.

Set the navigation bar color

Set the background color of the navigation bar to any hexadecimal color, or pass 'transparent' to make it fully transparent. Only available on Android:

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

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

Set the button style

Choose dark or light navigation bar buttons, or use Style.Default to follow the current device appearance. Only available on Android:

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

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

Read the current color and style

Get the current background color and button style of the navigation bar. Only available on Android:

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

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

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

Hide and show the navigation bar

Hide the navigation bar on demand, for example for fullscreen content, and show it again afterwards. Only available on Android:

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

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.

Since: 8.0.0

setStyle(...)

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

Set the style of the navigation bar buttons.

Only available on Android.

Since: 8.0.0

show()

show() => Promise<void>

Show the navigation bar.

Only available on Android.

Since: 8.0.0

Interfaces

GetColorResult

GetStyleResult

SetColorOptions

SetStyleOptions

Enums

Style

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.

How do I make the navigation bar transparent?

Pass 'transparent' as the color to the setColor method or use it as the color value in the Capacitor configuration. You can also pass 'transparent' as the dividerColor to hide the navigation bar divider.

Can I apply a color and style at app launch?

Yes, you can define the color, dividerColor, and style properties in the NavigationBar section of your Capacitor configuration file. The plugin applies these defaults when the app launches, so you don't have to call setColor or setStyle manually. See the Configuration section for examples.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

• Android Dark Mode Support: Seamless dark mode support for Android with prefers-color-scheme compatibility.
• Android Edge-to-Edge Support: Support edge-to-edge display on Android, including setting the background color of the status bar and navigation bar.
• Home Indicator: Hide and show the home indicator on iOS.
• Screen Orientation: Lock and unlock the screen orientation.

Newsletter

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

Changelog

See CHANGELOG.md.

License

See LICENSE.