# cordova-plugin-statusbar: painting the bar your Cordova app lives under

> The Apache Cordova StatusBar plugin gives a Cordova app one global StatusBar object for overlaying, recolouring, hiding and reacting to taps on the iOS and Android status bar. It is small, platform limited to two operating systems, and its iOS behaviour still depends on hand editing Info.plist and the viewport meta tag.

**apache/cordova-plugin-statusbar** — Apache Cordova Status Bar Plugin

- Repository: https://github.com/apache/cordova-plugin-statusbar
- Website: https://cordova.apache.org/
- Stars: 616 · Forks: 483
- Language: Objective-C
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/apache-cordova-plugin-statusbar

## A status bar that Cordova apps cannot otherwise touch

A Cordova app is a web view hosted in a native shell. The web view owns the page, but the strip of screen above it belongs to the operating system, and by default the operating system decides what it looks like. The StatusBar plugin exists to give the web side a handle on that strip.

The README states the intent plainly: the `StatusBar` object provides some functions to customize the iOS and Android StatusBar. The audience is Cordova developers who need a full-bleed layout with the bar drawn over the web view, a bar coloured to match a design system, a bar hidden during media playback, or a tap on the bar detected so the app can scroll back to the top.

The surface area is deliberately tiny. The README lists seven methods, `overlaysWebView`, `styleDefault`, `styleLightContent`, `backgroundColorByName`, `backgroundColorByHexString`, `hide` and `show`, one property, `isVisible`, and one event, `statusTap`. There is no configuration object, no queueing, no promise layer. Everything is a direct call on a global.

The primary language of the repository is Objective-C, and the tree matches a Cordova plugin layout with `src/`, `www/`, `types/`, `tests/` and a `plugin.xml`. The `www/` directory holds the JavaScript surface, `src/` holds the native implementations, and `types/index.d.ts` is what `package.json` points at for TypeScript definitions.

## A global object that only exists after deviceready

The one behaviour that catches people out is ordering. The plugin defines a global `StatusBar` object, and the README is explicit that although it is in the global scope, it is not available until after the `deviceready` event. Calling `StatusBar.hide()` at the top of a script that runs before that event is a no-op or an error, depending on how your page is structured.

The pattern the README gives is the standard Cordova readiness hook:

```js
    document.addEventListener("deviceready", onDeviceReady, false);
    function onDeviceReady() {
        console.log(StatusBar);
    }
```

From there, the calls map onto the two native platforms differently, and the documentation treats the platforms separately throughout. `overlaysWebView(true)` makes the bar sit over the web view instead of pushing it down. `styleDefault` and `styleLightContent` control the text colour, which is the `StatusBarStyle` idea in runtime form. `backgroundColorByName` and `backgroundColorByHexString` set the bar colour, and those two are Android concepts in practice: the README's Android section is where they are recommended, using the fact that Android 5 and later guidelines ask for a status bar colour that differs from the app's main colour.

`hide` and `show` work at runtime on both platforms, but startup hiding on iOS needs manual work in Info.plist, which is a separate mechanism rather than a method call.

## Adding the plugin and setting the startup preferences

Installation is a single Cordova command, and the README states that this method requires cordova 5.0 or later:

```bash
    cordova plugin add cordova-plugin-statusbar
```

There is a second route, from the repository URL, and the README labels it unstable:

```bash
    cordova plugin add https://github.com/apache/cordova-plugin-statusbar.git
```

Startup behaviour is set through `config.xml` preferences rather than JavaScript. The three that matter most are shown here:

```xml
        <preference name="StatusBarOverlaysWebView" value="true" />
        <preference name="StatusBarBackgroundColor" value="#000000" />
        <preference name="StatusBarStyle" value="lightcontent" />
```

`StatusBarOverlaysWebView` is a boolean and defaults to true, meaning the bar overlays the web view at startup unless you turn that off. `StatusBarBackgroundColor` takes a hex string with no default value, and if you do not set it the background stays transparent. `StatusBarStyle` defaults to `lightcontent`, and the README lists exactly two available options, `default` and `lightcontent`.

The first real use is then a runtime call, guarded by platform, to match a screen colour:

```js
if (cordova.platformId == 'android') {
    StatusBar.backgroundColorByHexString("#333");
}
```

That snippet changes the bar colour at runtime on Android only, and it is the documented pattern because the Android guidelines recommend a bar colour distinct from the main app colour.

## iOS transparency, Android alpha, and two different requirements

The two platforms disagree about almost every preference, and the README keeps them in separate subsections for a reason.

On iOS, setting `StatusBarOverlaysWebView` to true makes the status bar transparent, and a background colour cannot be applied. Since iOS 11 you must also include `viewport-fit=cover` in the viewport meta tag if you want the bar to overlay the web view:

```html
    <meta name="viewport" content="initial-scale=1, width=device-width, viewport-fit=cover">
```

That single meta tag line is the most commonly missed step. Without it, the CSS thinks the safe area ends above the bar, so full-bleed content stops short and the layout looks wrong even though the plugin is working.

On Android, the overlay preference is only supported on Android 5 or later, and earlier versions ignore it. Colour is expressed differently as well: when `StatusBarOverlaysWebView` is true, an eight digit hex string in the form #AARRGGBB can define transparency, where the AA pair is the alpha channel. That means decimal opacity values must be converted by hand before they can be used:

```js
if (cordova.platformId == 'android') {
    StatusBar.overlaysWebView(true);
    StatusBar.backgroundColorByHexString('#33000000');
}
```

This snippet gives a black bar at 20 percent opacity. It is workable, but the conversion from a percentage to ARGB hex is a manual step with no helper in the API, and it is the kind of detail that tends to live in a design token file rather than in application code.

## Hiding the bar at startup on iOS means editing Info.plist

Runtime hiding is easy: the README lists `StatusBar.hide` among the methods, and `StatusBar.isVisible` lets you check the current state. Startup hiding on iOS is not.

The README is direct about it: if you want the status bar hidden at app startup on iOS, you must modify the app's Info.plist file. Two attributes need to be added or edited. Set "Status bar is initially hidden" to "YES" and set "View controller-based status bar appearance" to "NO". If you edit the file by hand rather than through Xcode, the keys and values are:

```xml
	<key>UIStatusBarHidden</key>
	<true/>
	<key>UIViewControllerBasedStatusBarAppearance</key>
	<false/>
```

This is the plugin's biggest structural limitation. A Cordova plugin that wants to affect a value before the first frame has to reach outside the JavaScript runtime into a native project file, and the developer has to keep that edit in step with the platform project. It also means the hidden-at-start behaviour is not something a build script or a config.xml preference can express.

A second quirk sits next to it. `StatusBarDefaultScrollToTop` defaults to false so that the plugin's `statusTap` event can be handled instead. On iOS, tapping the bar is otherwise the system's way to scroll back to the top, and the plugin takes that gesture over by default, so an app that never registers a `statusTap` listener loses the platform behaviour.

## Two platforms, no release tags, and a version in development

The manifest is candid about the boundaries. `package.json` lists the plugin's platforms as `android` and `ios`, and the README's method list, preference list and quirks are all written against those two systems. There is no browser, Windows or desktop implementation here, so an application built on this plugin cannot be shipped to other targets through the same code path.

The dependency engine mapping in `package.json` shows the compatibility ladder. Version 0.1.0 of the plugin requires cordova 3.0.0 or later, version 4.0.0 requires cordova-android 10.0.0 or later and cordova-ios 6.0.0 or later, and the 5.0.0 entry lists cordova greater than 100, which reads as a placeholder rather than a real constraint. The declared version in the manifest is 4.0.1-dev, so the tree on the default branch is ahead of a published package.

Release information is thin in the same way. The repository has no GitHub releases, and there is a RELEASENOTES.md file instead, plus a release-audit workflow badge in the README badges. The last push was on 2026-10-05, the repository is not archived, and the default branch is master. The CI badges show separate test suites for Android, Chrome, iOS and lint, with the Node workflow run against the master branch.

Licensing is the easy part. The project is released under Apache-2.0, with a LICENSE file and a NOTICE file at the top level, a `licence_checker.yml` configuration, and a `licence_checker` setup that is standard for Apache Software Foundation repositories. Apache-2.0 grants broad use and modification rights including commercial use, with the conditions of preserving the licence and notice files, though the licence text is what governs any particular use.

## Conclusion

Adopt cordova-plugin-statusbar when your Cordova app needs the status bar to blend into the web view, change colour per screen on Android, or report a status bar tap to the user, and you are targeting only Android and iOS. Do not adopt it for a project that also ships to other platforms through Cordova, that needs the bar hidden before the first frame on iOS without touching Info.plist, or that expects a published release stream, since the repository has no GitHub releases and the manifest version is 4.0.1-dev. Before wiring it up, set StatusBarOverlaysWebView in config.xml, add viewport-fit=cover to the viewport meta tag for iOS 11 and later, and check the StatusBarStyle values you need against the two the README lists.

## FAQ

### How do I install cordova-plugin-statusbar?

Run `cordova plugin add cordova-plugin-statusbar`, which the README says requires cordova 5.0 or later. Installing straight from the repository URL with `cordova plugin add https://github.com/apache/cordova-plugin-statusbar.git` is also possible but is described as unstable.

### Why is StatusBar undefined when my Cordova app starts?

The plugin defines a global `StatusBar` object, but it is not available until after the `deviceready` event fires. Wait for `deviceready` before calling any StatusBar method.

### How do I make the status bar overlay the web view on iOS?

Set the `StatusBarOverlaysWebView` preference to true in config.xml, and since iOS 11 also include `viewport-fit=cover` in the viewport meta tag. On iOS the bar becomes transparent when it overlays the web view and no background colour can be applied.

### How do I set a semi-transparent status bar on Android?

Android uses hexadecimal ARGB values in the #AARRGGBB form, where the AA pair is the alpha channel, so you must convert your decimal opacity to hex yourself. The README shows a black bar at 20 percent opacity using `StatusBar.backgroundColorByHexString('#33000000')`.

### Can cordova-plugin-statusbar hide the status bar before the app launches on iOS?

Not through the JavaScript API. The README states that hiding the status bar at startup on iOS requires editing the app's Info.plist to set UIStatusBarHidden to true and UIViewControllerBasedStatusBarAppearance to false. The `StatusBar.hide` method works at runtime.

### Which platforms does cordova-plugin-statusbar support?

The package manifest lists `android` and `ios` as the supported platforms, and the README documents preferences and quirks only for those two. The engine mapping ties version 4.0.0 of the plugin to cordova-android 10.0.0 or later and cordova-ios 6.0.0 or later.

## Sources

- [apache/cordova-plugin-statusbar on GitHub](https://github.com/apache/cordova-plugin-statusbar)
- [Issues](https://github.com/apache/cordova-plugin-statusbar/issues)
- [License: Apache-2.0](https://github.com/apache/cordova-plugin-statusbar/blob/master/LICENSE)
- [Project website](https://cordova.apache.org/)
- [README](https://github.com/apache/cordova-plugin-statusbar/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/apache-cordova-plugin-statusbar