SystemBars

The SystemBars API provides methods for configuring the style and visibility of the device System Bars / Status Bar. This plugin is bundled with @capacitor/core.

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 has two ways to workaround this. To control this behavior, use the insetsHandling configuration setting.

You should also consider calling EdgeToEdge.enable(this); inside your application's BridgeActivity.onCreate if insetsHandling is not set to disable. Starting in Capacitor 9, insetsHandling will default to native and this will be called for you.

Example

import { SystemBars, SystemBarsStyle, SystemBarType } 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
insetsHandling	string	Specifies how to handle problematic insets on Android. This option is only supported on Android. native = (recommended) For older Chromium versions (< v140) this embeds the webview with padding and sets the env(safe-area-inset-*) variables to 0px. For newer Chromium versions (>= v140) this makes sure the webview adheres to the viewport-fit meta tag. If set to viewport-fit="cover" this will make the webview edge-to-edge and the env(safe-area-inset-*) variables will contain the correct values. With those values you could set padding for example so make sure the webview is shown correctly. css = This is the same as native, but it also injects CSS variables (--safe-area-inset-*) containing correct safe area inset values into the webview. disable = (not recommended) Disable safe area insets handling completely. This shifts the responsibility from Capacitor to your own code to handle the insets. Be aware that this might result in a visually broken UI if your native app code and the content loaded into the webview do not correctly handle safe area insets.	css
initialViewportFitValueHint	string	Set an initial value for the to be detected viewport-fit= meta tag value. For most apps that support edge-to-edge this value will eventually be cover. Therefore you might want to set this value to cover to help prevent layout jumps and glitches. If you know the value to be cover initially, you can set it here. The value will always end up correctly, no matter what you set here, as long as insetsHandling is set to native or css. It only exists to help prevent layout jumps and glitches. This option is only supported on Android.	undefined
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": {
      "insetsHandling": "css",
      "style": "DARK",
      "hidden": false,
      "animation": "NONE"
    }
  }
}

In capacitor.config.ts:

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

const config: CapacitorConfig = {
  plugins: {
    SystemBars: {
      insetsHandling: "css",
      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