Skip to main content
Version: v6

@capacitor/status-bar

The StatusBar API Provides methods for configuring the style of the Status Bar, along with showing or hiding it.

Installโ€‹

npm install @capacitor/status-bar
npx cap sync

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.

setBackgroundColor and setOverlaysWebView are currently not supported on iOS devices.

Exampleโ€‹

import { StatusBar, Style } from '@capacitor/status-bar';

// iOS only
window.addEventListener('statusTap', function () {
console.log('statusbar tapped');
});

// Display content under transparent status bar (Android only)
StatusBar.setOverlaysWebView({ overlay: true });

const setStatusBarStyleDark = async () => {
await StatusBar.setStyle({ style: Style.Dark });
};

const setStatusBarStyleLight = async () => {
await StatusBar.setStyle({ style: Style.Light });
};

const hideStatusBar = async () => {
await StatusBar.hide();
};

const showStatusBar = async () => {
await StatusBar.show();
};

APIโ€‹

setStyle(...)โ€‹

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

Set the current style of the status bar.

ParamType
options
StyleOptions

Since: 1.0.0


setBackgroundColor(...)โ€‹

setBackgroundColor(options: BackgroundColorOptions) => Promise<void>

Set the background color of the status bar.

This method is only supported on Android.

ParamType
options
BackgroundColorOptions

Since: 1.0.0


show(...)โ€‹

show(options?: AnimationOptions | undefined) => Promise<void>

Show the status bar. On iOS, if the status bar is initially hidden and the initial style is set to UIStatusBarStyleLightContent, first show call might present a glitch on the animation showing the text as dark and then transition to light. It's recommended to use Animation.None as the animation on the first call.

ParamType
options
AnimationOptions

Since: 1.0.0


hide(...)โ€‹

hide(options?: AnimationOptions | undefined) => Promise<void>

Hide the status bar.

ParamType
options
AnimationOptions

Since: 1.0.0


getInfo()โ€‹

getInfo() => Promise<StatusBarInfo>

Get info about the current state of the status bar.

Returns:

Promise<StatusBarInfo>

Since: 1.0.0


setOverlaysWebView(...)โ€‹

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

Set whether or not the status bar should overlay the webview to allow usage of the space underneath it.

This method is only supported on Android.

ParamType
options
SetOverlaysWebViewOptions

Since: 1.0.0


Interfacesโ€‹

StyleOptionsโ€‹

PropTypeDescriptionSince
style
Style
Style of the text of the status bar.1.0.0

BackgroundColorOptionsโ€‹

PropTypeDescriptionSince
colorstringA hex color to which the status bar color is set. This option is only supported on Android.1.0.0

AnimationOptionsโ€‹

PropTypeDescriptionDefaultSince
animation
Animation
The type of status bar animation used when showing or hiding. This option is only supported on iOS.Animation.Fade1.0.0

StatusBarInfoโ€‹

PropTypeDescriptionSince
visiblebooleanWhether the status bar is visible or not.1.0.0
style
Style
The current status bar style.1.0.0
colorstringThe current status bar color. This option is only supported on Android.1.0.0
overlaysbooleanWhether the statusbar is overlaid or not. This option is only supported on Android.1.0.0

SetOverlaysWebViewOptionsโ€‹

PropTypeDescriptionSince
overlaybooleanWhether to overlay the status bar or not.1.0.0

Enumsโ€‹

Styleโ€‹

MembersValueDescriptionSince
Dark'DARK'Light text for dark backgrounds.1.0.0
Light'LIGHT'Dark text for light backgrounds.1.0.0
Default'DEFAULT'The style is based on the device appearance. If the device is using Dark mode, the statusbar text will be light. If the device is using Light mode, the statusbar text will be dark. On Android the default will be the one the app was launched with.1.0.0

Animationโ€‹

MembersValueDescriptionSince
None'NONE'No animation during show/hide.1.0.0
Slide'SLIDE'Slide animation during show/hide. It doesn't work on iOS 15+.1.0.0
Fade'FADE'Fade animation during show/hide.1.0.0