@capawesome/capacitor-navigation-bar

v8.0.1

Published

22 days ago

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

0High
0Medium
0Low

capacitor capacitor-plugin plugin native ionic android ios navigation bar android navigation bar navigation bar color hide navigation bar system bars system ui

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.
🔁 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

| 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

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()

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

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.

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 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.
Android Dark Mode Support: Seamless dark mode support for Android with prefers-color-scheme compatibility.
Screen Orientation: Lock and unlock the screen orientation.

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Capacitor Navigation Bar Plugin

Features

Use Cases

Compatibility

Installation

Configuration

Examples

Usage

Set the navigation bar color

Set the button style

Read the current color and style

Hide and show the navigation bar

API

getColor()

getStyle()

hide()

setColor(...)

setStyle(...)

show()

Interfaces

GetColorResult

GetStyleResult

SetColorOptions

SetStyleOptions

Enums

Style

FAQ

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

Why is this plugin not available on iOS?

How do I make the navigation bar transparent?

Can I apply a color and style at app launch?

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

Related Plugins

Newsletter

Changelog

License

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