@capacitor/status-bar

What is @capacitor/status-bar?

@capacitor/status-bar is a Capacitor plugin that provides an interface for managing the status bar on iOS and Android devices. It allows you to show or hide the status bar, change its style, and set its background color.

What are @capacitor/status-bar's main functionalities?

Hide Status Bar

This feature allows you to hide the status bar on both iOS and Android devices.

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

StatusBar.hide();

Show Status Bar

This feature allows you to show the status bar if it was previously hidden.

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

StatusBar.show();

Set Status Bar Style

This feature allows you to change the style of the status bar. You can set it to 'Dark' or 'Light'.

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

StatusBar.setStyle({ style: Style.Dark });

Set Status Bar Background Color

This feature allows you to set the background color of the status bar. The color should be provided in hex format.

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

StatusBar.setBackgroundColor({ color: '#FF0000' });

Other packages similar to @capacitor/status-bar

cordova-plugin-statusbar

cordova-plugin-statusbar is a Cordova plugin that provides similar functionalities for managing the status bar on iOS and Android devices. It allows you to hide or show the status bar, change its style, and set its background color. Compared to @capacitor/status-bar, it is designed for use with Cordova rather than Capacitor.

react-native-status-bar-height

react-native-status-bar-height is a React Native package that provides utilities for getting the height of the status bar on iOS and Android devices. While it does not offer the same level of control over the status bar as @capacitor/status-bar, it is useful for layout purposes in React Native applications.

README

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

Example

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

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

// Display content under transparent status bar
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();
};

Configuration

These config values are available:

Prop	Type	Description	Default	Since
overlaysWebView	boolean	Whether the statusbar is overlaid or not. For applications targeting Android 15, this property has no effect unless the property windowOptOutEdgeToEdgeEnforcement is added to the application layout file. Otherwise, the application assumes always overlays as true. More details in https://developer.android.com/reference/android/R.attr#windowOptOutEdgeToEdgeEnforcement	true	1.0.0
style	string	Style of the text of the status bar.	default	1.0.0
backgroundColor	string	Color of the background of the statusbar in hex format, #RRGGBB. Doesn't work if overlaysWebView is true.	#000000	1.0.0

Examples

In capacitor.config.json:

{
  "plugins": {
    "StatusBar": {
      "overlaysWebView": false,
      "style": "DARK",
      "backgroundColor": "#ffffffff"
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capacitor/status-bar" />

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

const config: CapacitorConfig = {
  plugins: {
    StatusBar: {
      overlaysWebView: false,
      style: "DARK",
      backgroundColor: "#ffffffff",
    },
  },
};

export default config;

API

• setStyle(...)
• setBackgroundColor(...)
• show(...)
• hide(...)
• getInfo()
• setOverlaysWebView(...)
• Interfaces
• Enums

setStyle(...)

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

Set the current style of the status bar.

Param	Type
options	StyleOptions

Since: 1.0.0

---

setBackgroundColor(...)

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

Set the background color of the status bar.

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

Param	Type
options	AnimationOptions

Since: 1.0.0

---

hide(...)

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

Hide the status bar.

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

Param	Type
options	SetOverlaysWebViewOptions

Since: 1.0.0

---

Interfaces

StyleOptions

Prop	Type	Description	Since
style	Style	Style of the text of the status bar.	1.0.0

BackgroundColorOptions

Prop	Type	Description	Since
color	string	A hex color to which the status bar color is set.	1.0.0

AnimationOptions

Prop	Type	Description	Default	Since
animation	Animation	The type of status bar animation used when showing or hiding. This option is only supported on iOS.	Animation.Fade	1.0.0

StatusBarInfo

Prop	Type	Description	Since
visible	boolean	Whether the status bar is visible or not.	1.0.0
style	Style	The current status bar style.	1.0.0
color	string	The current status bar color.	1.0.0
overlays	boolean	Whether the statusbar is overlaid or not.	1.0.0

SetOverlaysWebViewOptions

Prop	Type	Description	Since
overlay	boolean	Whether to overlay the status bar or not.	1.0.0

Enums

Style

Members	Value	Description	Since
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

Members	Value	Description	Since
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