capacitor-plugin-status-bar

Capacitor status bar

Install

npm install capacitor-plugin-status-bar
npx cap sync

Configuration

iOS

For the show() and hide() methods to work on iOS, you need to configure your app's Info.plist:

1. Open ios/App/App/Info.plist
2. Add or modify the following key:

<key>UIViewControllerBasedStatusBarAppearance</key>
<false/>

Note: Starting with iOS 13, Apple deprecated the application-level status bar control API in favor of view controller-based appearance. Setting UIViewControllerBasedStatusBarAppearance to false allows this plugin to control the status bar programmatically. This is the recommended approach for Capacitor plugins.

Android

No additional configuration required. The plugin works out of the box on Android.

API

• setStyle(...)
• show()
• hide()
• setOverlaysWebView(...)
• showNavigationBar()
• hideNavigationBar()
• getSafeAreaInsets()
• Type Aliases
• Enums

setStyle(...)

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

Set the status bar and navigation bar style and color.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | ---------------------------------------------------- | | options | StatusBarStyleOptions | - The options to set the status bar style and color. |

show()

show() => Promise<void>

Show the status bar and navigation bar.

hide()

hide() => Promise<void>

Hide the status bar and navigation bar with a slide animation.

setOverlaysWebView(...)

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

Set whether the status bar overlays the web view.

iOS only - On Android this is a no-op (resolves without error).

• true: Web content extends behind the status bar (transparent background), allowing content to be visible through the status bar area on scroll.
• false: Restores the status bar background to the color set by setStyle or falls back to the default style from Capacitor config.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | options | StatusBarSetOverlaysWebViewOptions | - The options to set the status bar overlays web view. |

showNavigationBar()

showNavigationBar() => Promise<void>

Show the navigation bar.

hideNavigationBar()

hideNavigationBar() => Promise<void>

Hide the navigation bar with a slide animation (hides completely from screen).

getSafeAreaInsets()

getSafeAreaInsets() => Promise<SafeAreaInsets>

Get the safe area insets. Returns the insets for status bar, navigation bar, and notch areas. Values are in CSS pixels (dp) on all platforms.

Returns: Promise<SafeAreaInsets>

Type Aliases

StatusBarOptions

StatusBarStyleOptions

StatusBarStyleOptions

StatusBarStyleNoDefaultOptions | { style: Style.CUSTOM; color: StatusBarColor; }

StatusBarStyleNoDefaultOptions

{ style: Style; }

StatusBarColor

Full HEX color format only (6 or 8 digits).

• 6 digits: #RRGGBB (e.g., #FFFFFF, #000000, #FF5733)
• 8 digits: #RRGGBBAA with alpha channel (e.g., #FFFFFF00, #FF5733CC)

Note: Short 3-digit format (#FFF) is NOT supported.

#${string}

StatusBarSetOverlaysWebViewOptions

{ value: boolean; }

SafeAreaInsets

{ top: number; bottom: number; left: number; right: number; }

Enums

Style

| Members | Value | | ------------ | --------------------- | | LIGHT | 'LIGHT' | | DARK | 'DARK' | | CUSTOM | 'CUSTOM' |