@capacitor/status-bar

The StatusBar API Provides methods for configuring the style of the Status Bar, along with showing or hiding it.

Install

npm install @capacitor/status-bar
npx cap sync

Android 16+ behavior change

For apps targeting Android 16 (API level 36) and higher using Capacitor 8, the following Status Bar configuration options no longer work:

• overlaysWebView
• backgroundColor

These options relied on the ability to opt out of Android’s edge-to-edge behavior, which was still possible in Android 15 but is no longer supported in Android 16+. For more context, see the previous behavior documented for Android 15 opt-out.

Alternatives

The Android platform now enforces edge-to-edge system UI, which removes direct control over the status bar background and overlay behavior.

If you need to adjust the system bars appearance on Android 16+, consider:

• Using the System Bars core plugin.
• Exploring community plugins such as @capacitor‑community/safe‑area or @capawesome/capacitor‑android‑edge‑to‑edge‑support

Note that these APIs behave differently across Android versions and may not fully replicate the legacy overlaysWebView or backgroundColor functionality.

iOS Note

This plugin requires "View controller-based status bar appearance" (UIViewControllerBasedStatusBarAppearance) set to YES in Info.plist. Read about Configuring iOS for help.

The status bar visibility defaults to visible and the style defaults to Style.Default. You can change these defaults by adding UIStatusBarHidden and/or UIStatusBarStyle in Info.plist.

Example

import { StatusBar, Style } from '@capacitor/status-bar';

// iOS only
window.addEventListener('statusTap', function () {
  console.log('statusbar tapped');
});

// Display content under transparent status bar
StatusBar.setOverlaysWebView({ overlay: true });

const setStatusBarStyleDark = async () => {
  await StatusBar.setStyle({ style: Style.Dark });
};

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

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

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

Configuration

{
  "plugins": {
    "StatusBar": {
      "overlaysWebView": false,
      "style": "DARK",
      "backgroundColor": "#ffffffff"
    }
  }
}

/// <reference types="@capacitor/status-bar" />

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

const config: CapacitorConfig = {
  plugins: {
    StatusBar: {
      overlaysWebView: false,
      style: "DARK",
      backgroundColor: "#ffffffff",
    },
  },
};

export default config;

API

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

setBackgroundColor(options: BackgroundColorOptions) => Promise<void>

show(options?: AnimationOptions | undefined) => Promise<void>

hide(options?: AnimationOptions | undefined) => Promise<void>

getInfo() => Promise<StatusBarInfo>

setOverlaysWebView(options: SetOverlaysWebViewOptions) => Promise<void>