Skip to main content

Status Bar

EOL Notice

Status Bar will reach its end-of-life on July 1, 2024, and will no longer receive updates or support. Please see Support Policy for additional information.

The Status Bar plugin provides the ability to customize the appearance of the native mobile status bar, including setting visibility, background color, and more.

Installation

If you have not already setup Ionic Enterprise in your app, follow the one-time setup steps.

Next, install the plugin:

Available as a core Capacitor plugin.

Preferences

You can add the following preferences in your config.xml:

  • StatusBarOverlaysWebView (boolean, defaults to true). Make the statusbar overlay or not overlay the WebView at startup.

     <preference name="StatusBarOverlaysWebView" value="true" />

  • StatusBarBackgroundColor (color hex string, no default value). 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.

      <preference name="StatusBarBackgroundColor" value="#000000" />

  • StatusBarStyle (status bar style, defaults to lightcontent). Set the status bar style (e.g. text color). Available options: default, lightcontent, blacktranslucent, blackopaque.

      <preference name="StatusBarStyle" value="lightcontent" />

  • StatusBarDefaultScrollToTop (boolean, defaults to false). On iOS, allows the Cordova WebView to use default scroll-to-top behavior. Defaults to false so you can listen to the "statusTap" event (described below) and customize the behavior instead.

      <preference name="StatusBarDefaultScrollToTop" value="false" />

Index

Classes

Classes

StatusBar

StatusBar:

name: Status Bar

description: Manage the appearance of the native status bar.

usage:

import { StatusBar } from '@ionic-enterprise/statusbar/ngx';

constructor(private statusBar: StatusBar) { }

...

// let status bar overlay webview
this.statusBar.overlaysWebView(true);

// set status bar to white
this.statusBar.backgroundColorByHexString('#ffffff');

isVisible

● isVisible: boolean

Whether the StatusBar is currently visible or not.

backgroundColorByHexString

▸ backgroundColorByHexString(hexString: string): void

Set the status bar to a specific hex color (CSS shorthand supported!).

iOS note: you must call StatusBar.overlaysWebView(false) to enable color changing.

Parameters:

NameTypeDescription
hexStringstringThe hex value of the color.

Returns: void

backgroundColorByName

▸ backgroundColorByName(colorName: string): void

Set the status bar to a specific named color. Valid options: black, darkGray, lightGray, white, gray, red, green, blue, cyan, yellow, magenta, orange, purple, brown.

iOS note: you must call StatusBar.overlaysWebView(false) to enable color changing.

Parameters:

NameTypeDescription
colorNamestringThe name of the color (from above)

Returns: void

hide

▸ hide(): void

Hide the StatusBar

Returns: void

overlaysWebView

▸ overlaysWebView(doesOverlay: boolean): void

Set whether the status bar overlays the main app view. The default is true.

Parameters:

NameTypeDescription
doesOverlaybooleanWhether the status bar overlays the main app view.

Returns: void

show

▸ show(): void

Show the StatusBar

Returns: void

styleBlackOpaque

▸ styleBlackOpaque(): void

Use the blackOpaque statusbar (light text, for dark backgrounds).

Returns: void

styleBlackTranslucent

▸ styleBlackTranslucent(): void

Use the blackTranslucent statusbar (light text, for dark backgrounds).

Returns: void

styleDefault

▸ styleDefault(): void

Use the default statusbar (dark text, for light backgrounds).

Returns: void

styleLightContent

▸ styleLightContent(): void

Use the lightContent statusbar (light text, for dark backgrounds).

Returns: void

Release Notes

2.5.0 (Nov 1, 2019)

  • fix(ios): make default set black text on iOS 13 too
  • fix(iOS): Delay resizeWebView on viewWillAppear for correct statusbar height (#157)

2.4.3 (Jun 19, 2019)

  • docs: Improved documentation and removed text that implies iOS only (#130) (33e410a, 14b1513)
  • docs: Alpha example doesn't match description (#100) (5b77cae, 9b5baa2)
  • chore(types): remove version from types (fade76b)
  • chore: fix github issues link (288bd71)
  • docs: remove outdated translations (8dacefa)
  • build: add .npmignore to remove unneeded files from npm package (84081de)
  • build: add .gitattributes to force LF (instead of possible CRLF on Windows) (da6c2a8)
  • ci(travis): Update Travis CI configuration for new paramedic (#139) (a538bfe)
  • feat: update typings (#132) (003fa61)
  • chore: drop Node.js v4 support (#124) (a07612a)
  • chore(github): Add or update GitHub pull request and issue template (727eea3)
  • docs: remove JIRA link (adcee9f)
  • ci(travis): also accept terms for android sdk android-27 (c8a13b8)
  • docs: remove second title headline (ecf8ccd)
  • docs: Add Android overlay support to README (#97) (e0256b2, 053a902)

2.4.2 (Apr 12, 2018)

2.4.1 (Dec 27, 2017)

  • CB-13712 (iOS): fix overlaysWebView reset on rotation (#92)

2.4.0 (Dec 15, 2017)

2.3.0 (Nov 06, 2017)

  • CB-13476 (iOS): handle double size statusbar on SDK 10 for iOS 11
  • CB-13394 (iOS): fix iPhone X StatusBar rendering in landscape
  • CB-11858 (android) Add StatusBarStyle feature support for Android M+
  • CB-13311 (iOS) Statusbar does not overlay correctly on iPhone X
  • CB-13028 (CI) Browser builds on Travis and AppVeyor
  • CB-12812 (browser) Fix statusbar plugin with Browser platform
  • CB-12847 added bugs entry to package.json.

2.2.3 (Apr 27, 2017)

  • CB-12622 Added Android 6.0 build badge to README
  • CB-10879 Enable overlaysWebView on Android API 21+
  • CB-12685 added package.json to tests folder

2.2.2 (Feb 28, 2017)

  • CB-12188 Status Bar is not changing in some specific Android phone (Red MI 3s Prime)
  • CB-12369 Add plugin typings from DefinitelyTyped
  • CB-12363 Added build badges for iOS 9.3 and iOS 10.0
  • CB-12196 iOS fix Status Bar Not Hiding
  • CB-12141 iOS fix white app screen after camera overlay shown on iPad
  • CB-12230 Removed Windows 8.1 build badges

2.2.1 (Dec 07, 2016)

  • CB-12224 Updated version and RELEASENOTES.md for release 2.2.1
  • CB-10288 statusbar plugin interaction with iOS multitasking
  • CB-10158 (ios) fix StatusBar issue when recovering from fullscreen video
  • CB-10341 ios, document statusTap event
  • CB-11191 Statusbar plugin causing issues with webview size
  • CB-11917 - Remove pull request template checklist item: "iCLA has been submitted…"
  • CB-11832 Incremented plugin version.

2.2.0 (Sep 08, 2016)

  • CB-11795 Add 'protective' entry to cordovaDependencies
  • Handle extended status bar on iOS
  • Plugin uses Android Log class and not Cordova LOG class
  • CB-11287 (ios) - fix webview resize after modal on iPhones
  • CB-11485 fix resize on rotation with popover
  • Add badges for paramedic builds on Jenkins
  • CB-11197 Keep status bar hidden when keyboard pops up
  • Add pull request template.
  • CB-10866 Adding engine info to package.json
  • patched missing _ready method, and changed the way the proxy is installed
  • CB-10996 Adding front matter to README.md

2.1.3 (Apr 15, 2016)

  • CB-11018 Fix statusbar with inappbrowser causing incorrect orientation on iOS8
  • CB-10884 Inappbrowser breaks UI while Screen orientation changes from landscape to portrait on iOS

2.1.2 (Mar 09, 2016)

  • CB-10752 for for status bar overlays the webview on iOS 6 in some cases
  • CB-10683 Fix wrong StatusBar.isVisible initial value on Windows
  • CB-10636 Add JSHint for plugins
  • CB-10047 fix iOS 8 deprecated warnings

2.1.1 (Feb 09, 2016)

  • CB-10102 The removeObserver code was wrong and it might crash on plugin deallocation

2.1.0 (Jan 15, 2016)

  • CB-9513 Allow to show/hide status bar in fullscreen mode.
  • CB-8720 Fix status bar position when app started upside down on iOS 7.
  • CB-10118 Fixes plugin loading error for Browser platform

2.0.0 (Nov 18, 2015)

  • CB-10035 Updated RELEASENOTES to be newest to oldest
  • Added weakSelf reference for block use
  • Fixes CB-4712, CB-5439 statusbar issues
  • Fixing contribute link.
  • CB-7965 Add cordova-plugin-statusbar support for Browser platform
  • Don't use IsAtLeastiOSVersion macro to determine height
  • Use correct statusbar height for landscape orientation in iOS >= 8
  • remove travis-ci
  • CB-9202 updated repo url to github mirror in package.json
  • Added verbose install text for users on < cordova 5.0
  • update docs for StatusBarBackgroundColor

1.0.1 (Jun 17, 2015)

  • add auto-tests for basic api
  • CB-9180 Add correct supported check for Windows 8.1 desktop
  • CB-9128 cordova-plugin-statusbar documentation translation: cordova-plugin-statusbar
  • fix npm md issue

1.0.0 (Apr 15, 2015)

  • CB-8746 gave plugin major version bump
  • CB-8683 changed plugin-id to pacakge-name
  • CB-8653 properly updated translated docs to use new id
  • CB-8653 updated translated docs to use new id
  • Use TRAVIS_BUILD_DIR, install paramedic by npm
  • CB-8653 Updated Readme
    • Use StatusBarBackgroundColor instead of AndroidStatusBarBackgroundColor, and added a quirk to the readme.
    • Add support for StatusBar.backgroundColorByHexString (and StatusBar.backgroundColorByName) on Android 5 and up
  • Allow setting the statusbar backgroundcolor on Android
  • CB-8575 Integrate TravisCI
  • CB-8438 cordova-plugin-statusbar documentation translation: cordova-plugin-statusbar
  • CB-8538 Added package.json file

0.1.10 (Feb 04, 2015)

  • CB-8351 ios: Use argumentForIndex rather than NSArray extension

0.1.9 (Dec 02, 2014)

  • Fix onload attribute within <feature> to be a <param>
  • CB-8010 - Statusbar colour does not change to orange
  • added checks for running on windows when StatusBar is NOT available
  • CB-7986 Add cordova-plugin-statusbar support for Windows Phone 8.1
  • CB-7977 Mention deviceready in plugin docs
  • CB-7979 Each plugin doc should have a ## Installation section
  • Inserting leading space after # for consistency
  • CB-7549 - (Re-fix) StatusBar iOS 8 Landscape issue (closes #15)
  • CB-7700 cordova-plugin-statusbar documentation translation: cordova-plugin-statusbar
  • CB-7571 Bump version of nested plugin to match parent plugin

0.1.8 (Sep 17, 2014)

  • CB-7549 [StatusBar][ios 8] Landscape issue
  • CB-7486 Remove StatusBarBackgroundColor intial preference (black background) so background will be initially transparent
  • Renamed test dir, added nested plugin.xml
  • added documentation for manual tests, moved background color test below overlay test
  • CB-7195 ported statusbar tests to framework

0.1.7 (Aug 06, 2014)

  • Add LICENSE and NOTICE
  • Update statusbar.js
  • Update backgroundColorByHexString function
  • ios: Use a persistent callbackId instead of calling sendJs
  • CB-6626 ios: Add a JS event for tapping on statusbar
  • ios: Fix hide to adjust webview's frame only when status bar is not overlaying webview
  • CB-6127 Updated translations for docs
  • android: Fix StatusBar.initialize() not running on UI thread

0.1.6 (Jun 05, 2014)

  • CB-6783 - added StatusBarStyle config preference, updated docs (closes #9)
  • CB-6812 Add license
  • CB-6491 add CONTRIBUTING.md
  • CB-6264 minor formatting issue
  • Update docs with recent WP changes, remove 'clear' from the loist of named colors in documentation
  • CB-6513 - Statusbar plugin for Android is not compiling

0.1.5 (Apr 17, 2014) (First release as a core Cordova Plugin)

  • CB-6316: Added README.md which point to the new location for docs
  • CB-6316: Added license header to the documentation. Added README.md which point to the new location for docs
  • CB-6316: Moved StatusBar plugin documentation to docs folder
  • CB-6314: [android] Add StatusBar.isVisible support to Android
  • CB-6460: Update license headers