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(...)
• setBackground(...)
• 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(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.

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

setBackground(...)

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

Set the window background color.

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

showNavigationBar(...)

showNavigationBar(options: NavigationBarShowOptions) => Promise<void>

Show the navigation bar.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------------- | ----------------------------------------- | | options | NavigationBarShowOptions | - The options to show the navigation bar. |

hideNavigationBar(...)

hideNavigationBar(options: NavigationBarHideOptions) => Promise<void>

Hide the navigation bar.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------------- | ----------------------------------------- | | options | NavigationBarHideOptions | - The options to hide the navigation bar. |

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}

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; }

NavigationBarShowOptions

{ animated: boolean; }

NavigationBarHideOptions

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

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' |