cap-status-bar

Capacitor status bar

Install

npm install cap-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(...)
• setBackground(...)
• setStatusBarColor(...)
• 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(options: StatusBarShowOptions) => Promise<void>

Show the status bar.

| Param | Type | Description | | ------------- | --------------------------------------------------------------------- | ------------------------------------- | | options | StatusBarShowOptions | - The options to show the status bar. |

hide(...)

hide(options: StatusBarHideOptions) => Promise<void>

Hide the status bar.

| Param | Type | Description | | ------------- | --------------------------------------------------------------------- | ------------------------------------- | | options | StatusBarHideOptions | - The options to hide the status bar. |

setOverlaysWebView(...)

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

Set whether the status bar overlays the web view.

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

setBackground(...)

setBackground(options: StatusBarSetBackgroundOptions) => Promise<void>

Set the window background color.

| Param | Type | Description | | ------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------- | | options | StatusBarSetBackgroundOptions | - The options to set the window background color. |

setStatusBarColor(...)

setStatusBarColor(options: StatusBarSetColorOptions) => Promise<void>

Set the status bar color only.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------------- | ------------------------------------------ | | options | StatusBarSetColorOptions | - The options to set the status bar color. |

getSafeAreaInsets()

getSafeAreaInsets() => Promise<SafeAreaInsets>

Get the safe area insets. Returns the insets for status bar, navigation bar, and notch areas. Values are in pixels on Android and points on iOS.

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}

StatusBarShowOptions

{ animated: boolean; }

StatusBarHideOptions

{ /** * The animation type for hiding the status bar. * - 'fade': Makes the background transparent without removing the status bar and navigation bar. * - 'slide': Hides the status bar and navigation bar completely (default behavior). */ animation: StatusBarAnimation; }

StatusBarSetOverlaysWebViewOptions

{ value: boolean; }

StatusBarSetBackgroundOptions

{ color: StatusBarColor; }

StatusBarSetColorOptions

{ color: StatusBarColor; }

SafeAreaInsets

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

Enums

Style

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

StatusBarAnimation

| Members | Value | | ----------- | -------------------- | | NONE | 'none' | | FADE | 'fade' | | SLIDE | 'slide' |