SystemBars

The SystemBars API provides methods for configuring the style and visibility of the device System Bars / Status Bar. This API differs from the Status Bar plugin in that it is only intended to support modern edge to edge use cases moving forward. For legacy functionality, use the Status Bar plugin.

Feature	System Bars	Status Bar
setOverlaysWebView()	Unsupported	Supported on iOS and Android <= 14 (or 15 if edge to edge opt-out is enabled)
setBackgroundColor()	Unsupported	Supported
setStyle()	Supported	Supported - top Status Bar only
hide()/show()	Supported	Supported - top Status Bar only

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.

Android Note

Due to a bug in some older versions of Android WebView (< 140), correct safe area values are not available via the safe-area-inset-x CSS env variables. This plugin will inject the correct inset values into a new CSS variable(s) named --safe-area-inset-x that you can use as a fallback in your frontend styles:

html {
  padding-top: var(--safe-area-inset-top, env(safe-area-inset-top, 0px));
  padding-bottom: var(--safe-area-inset-bottom, env(safe-area-inset-bottom, 0px));
  padding-left: var(--safe-area-inset-left, env(safe-area-inset-left, 0px));
  padding-right: var(--safe-area-inset-right, env(safe-area-inset-right, 0px));
}

To disable the inset variable injections, set the configuration setting disableInsets to true.

Example

import { SystemBars, SystemBarsStyle } from '@capacitor/core';

const setSystemBarStyleDark = async () => {
  await SystemBars.setStyle({ style: SystemBarsStyle.Dark });
};

const setSystemBarStyleLight = async () => {
  await SystemBars.setStyle({ style: SystemBarsStyle.Light });
};

const hideSystemBars = async () => {
  await SystemBars.hide();
};

const showSystemBars = async () => {
  await SystemBars.show();
};

const hideNavigationBar = async () => {
  await SystemBars.hide({
    bar: SystemBarType.NavigationBar
  })
}

// Set the Status Bar animation, only on iOS
const setStatusBarAnimation = async () => {
  await SystemBars.setAnimation({ animation: "NONE" });
}

Configuration

Prop	Type	Description	Default
disableInsets	boolean	Disables the injection of device css insets into the webview. This option is only supported on Android.	false
style	string	The style of the text and icons of the system bars.	DEFAULT
hidden	boolean	Hide the system bars on start.	false
animation	string	The type of status bar animation used when showing or hiding. This option is only supported on iOS.	FADE

Example Configuration

In capacitor.config.json:

{
  "plugins": {
    "SystemBars": {
      "disableInsets": true,
      "style": "DARK",
      "hidden": false,
      "animation": "NONE"
    }
  }
}

In capacitor.config.ts:

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

const config: CapacitorConfig = {
  plugins: {
    SystemBars: {
      disableInsets: true,
      style: "DARK",
      hidden: false,
      animation: "NONE"
    },
  },
};

export default config;

API

• setStyle(...)
• show(...)
• hide(...)
• setAnimation(...)
• Interfaces
• Type Aliases
• Enums

setStyle(...)

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

Set the current style of the system bars.

Param	Type
options	SystemBarsStyleOptions

Since: 8.0.0

---

show(...)

show(options: SystemBarsVisibilityOptions) => Promise<void>

Show the system bars.

Param	Type
options	SystemBarsVisibilityOptions

Since: 8.0.0

---

hide(...)

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

Hide the system bars.

Param	Type
options	SystemBarsVisibilityOptions

Since: 8.0.0

---

setAnimation(...)

setAnimation(options: SystemBarsAnimationOptions) => Promise<void>

Set the animation to use when showing / hiding the status bar.

Only available on iOS.

Param	Type
options	SystemBarsAnimationOptions

Since: 8.0.0

---

Interfaces

SystemBarsStyleOptions

Prop	Type	Description	Default	Since
style	SystemBarsStyle	Style of the text and icons of the system bars.	'DEFAULT'	8.0.0
bar	SystemBarType	The system bar to which to apply the style.	null	8.0.0

SystemBarsVisibilityOptions

Prop	Type	Description	Default	Since
bar	SystemBarType	The system bar to hide or show.	null	8.0.0
animation	SystemBarsAnimation	The type of status bar animation used when showing or hiding. This option is only supported on iOS.	'FADE'	8.0.0

SystemBarsAnimationOptions

Prop	Type	Description	Default	Since
animation	SystemBarsAnimation	The type of status bar animation used when showing or hiding. This option is only supported on iOS.	'FADE'	8.0.0

Type Aliases

SystemBarsAnimation

Available status bar animations. iOS only.

'FADE' | 'NONE'

Enums

SystemBarsStyle

Members	Value	Description	Since
Dark	'DARK'	Light system bar content on a dark background.	8.0.0
Light	'LIGHT'	For dark system bar content on a light background.	8.0.0
Default	'DEFAULT'	The style is based on the device appearance or the underlying content. If the device is using Dark mode, the system bars content will be light. If the device is using Light mode, the system bars content will be dark.	8.0.0

SystemBarType

Members	Value	Description	Since
StatusBar	'StatusBar'	The top status bar on both Android and iOS.	8.0.0
NavigationBar	'NavigationBar'	The navigation bar (or gesture bar on iOS) on both Android and iOS.	8.0.0