[](https://travis-ci.org/apache/cordova-plugin-statusbar)
# cordova-plugin-statusbar
StatusBar
======
> The `StatusBar` object provides some functions to customize the iOS and Android StatusBar.
:warning: Report issues on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Statusbar%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC)
## Installation
This installation method requires cordova 5.0+
cordova plugin add cordova-plugin-statusbar
Older versions of cordova can still install via the __deprecated__ id
cordova plugin add org.apache.cordova.statusbar
It is also possible to install via repo url directly ( unstable )
cordova plugin add https://github.com/apache/cordova-plugin-statusbar.git
Preferences
-----------
#### config.xml
- __StatusBarOverlaysWebView__ (boolean, defaults to true). On iOS 7, make the statusbar overlay or not overlay the WebView at startup.
- __StatusBarBackgroundColor__ (color hex string, no default value). On iOS 7, set the background color of the statusbar by a hex string (#RRGGBB) at startup. If this value is not set, the background color will be transparent.
- __StatusBarStyle__ (status bar style, defaults to lightcontent). On iOS 7, set the status bar style. Available options default, lightcontent, blacktranslucent, blackopaque.
### Android Quirks
The Android 5+ guidelines specify using a different color for the statusbar than your main app color (unlike the uniform statusbar color of many iOS 7+ apps), so you may want to set the statusbar color at runtime instead via `StatusBar.backgroundColorByHexString` or `StatusBar.backgroundColorByName`. One way to do that would be:
```js
if (cordova.platformId == 'android') {
StatusBar.backgroundColorByHexString("#333");
}
```
Hiding at startup
-----------
During runtime you can use the StatusBar.hide function below, but if you want the StatusBar to be hidden at app startup, you must modify your app's Info.plist file.
Add/edit these two attributes if not present. Set **"Status bar is initially hidden"** to **"YES"** and set **"View controller-based status bar appearance"** to **"NO"**. If you edit it manually without Xcode, the keys and values are:
UIStatusBarHidden
UIViewControllerBasedStatusBarAppearance
Methods
-------
This plugin defines global `StatusBar` object.
Although in the global scope, it is not available until after the `deviceready` event.
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
console.log(StatusBar);
}
- StatusBar.overlaysWebView
- StatusBar.styleDefault
- StatusBar.styleLightContent
- StatusBar.styleBlackTranslucent
- StatusBar.styleBlackOpaque
- StatusBar.backgroundColorByName
- StatusBar.backgroundColorByHexString
- StatusBar.hide
- StatusBar.show
Properties
--------
- StatusBar.isVisible
Permissions
-----------
#### config.xml
StatusBar.overlaysWebView
=================
On iOS 7, make the statusbar overlay or not overlay the WebView.
StatusBar.overlaysWebView(true);
Description
-----------
On iOS 7, set to false to make the statusbar appear like iOS 6. Set the style and background color to suit using the other functions.
Supported Platforms
-------------------
- iOS
Quick Example
-------------
StatusBar.overlaysWebView(true);
StatusBar.overlaysWebView(false);
StatusBar.styleDefault
=================
Use the default statusbar (dark text, for light backgrounds).
StatusBar.styleDefault();
Supported Platforms
-------------------
- iOS
- Windows Phone 7
- Windows Phone 8
- Windows Phone 8.1
StatusBar.styleLightContent
=================
Use the lightContent statusbar (light text, for dark backgrounds).
StatusBar.styleLightContent();
Supported Platforms
-------------------
- iOS
- Windows Phone 7
- Windows Phone 8
- Windows Phone 8.1
StatusBar.styleBlackTranslucent
=================
Use the blackTranslucent statusbar (light text, for dark backgrounds).
StatusBar.styleBlackTranslucent();
Supported Platforms
-------------------
- iOS
- Windows Phone 7
- Windows Phone 8
- Windows Phone 8.1
StatusBar.styleBlackOpaque
=================
Use the blackOpaque statusbar (light text, for dark backgrounds).
StatusBar.styleBlackOpaque();
Supported Platforms
-------------------
- iOS
- Windows Phone 7
- Windows Phone 8
- Windows Phone 8.1
StatusBar.backgroundColorByName
=================
On iOS 7, when you set StatusBar.statusBarOverlaysWebView to false, you can set the background color of the statusbar by color name.
StatusBar.backgroundColorByName("red");
Supported color names are:
black, darkGray, lightGray, white, gray, red, green, blue, cyan, yellow, magenta, orange, purple, brown
Supported Platforms
-------------------
- iOS
- Android 5+
- Windows Phone 7
- Windows Phone 8
- Windows Phone 8.1
StatusBar.backgroundColorByHexString
=================
Sets the background color of the statusbar by a hex string.
StatusBar.backgroundColorByHexString("#C0C0C0");
CSS shorthand properties are also supported.
StatusBar.backgroundColorByHexString("#333"); // => #333333
StatusBar.backgroundColorByHexString("#FAB"); // => #FFAABB
On iOS 7, when you set StatusBar.statusBarOverlaysWebView to false, you can set the background color of the statusbar by a hex string (#RRGGBB).
On WP7 and WP8 you can also specify values as #AARRGGBB, where AA is an alpha value
Supported Platforms
-------------------
- iOS
- Android 5+
- Windows Phone 7
- Windows Phone 8
- Windows Phone 8.1
StatusBar.hide
=================
Hide the statusbar.
StatusBar.hide();
Supported Platforms
-------------------
- iOS
- Android
- Windows Phone 7
- Windows Phone 8
- Windows Phone 8.1
StatusBar.show
=================
Shows the statusbar.
StatusBar.show();
Supported Platforms
-------------------
- iOS
- Android
- Windows Phone 7
- Windows Phone 8
- Windows Phone 8.1
StatusBar.isVisible
=================
Read this property to see if the statusbar is visible or not.
if (StatusBar.isVisible) {
// do something
}
Supported Platforms
-------------------
- iOS
- Android
- Windows Phone 7
- Windows Phone 8
- Windows Phone 8.1