PhoneGap Developer’s Guide to the iOS Status Bar

July 31, 2014By 7 Comments

I wrote this post as a guide for PhoneGap Developer’s to use in handling and customizing the iOS Status Bar and to help clear up confusion where documentation is not clear. My testing and conclusions also resulted in the handy little Status Bar Simulator App below to help developers pick preferences to customize their apps visually for use with the Cordova StatusBar Plugin.

Try out the different options/combos right below in my Simulator app to see the effects on the status bar, then read on for details on what these preferences mean exactly as well as other tips on all things Status Bar.

Status Bar Simulator App – I’M A REAL APP, CLICK ON ME!

statusbar-problem

StatusBar and iOS7

If you’re building PhoneGap/Cordova applications for iOS, you’ve likely run into the iOS7 issue where the status bar overlaps the content in the top portion of your application where a navigation bar would typically display. This is due to the iOS7 change for ViewControllers (containing the WebView running your PhoneGap application) to display full screen by default with a transparent Status Bar overlaying it rather than having its own designated space in the top 20 pixels of the screen as before. You can see how the status bar now appears to blend in with the header content in the image below from the Apple docs showing iOS7 vs iOS6:

Screen Shot 2014-07-31 at 12.08.49 PM

Solutions

There are different ways to handle this iOS7 change in your applications. One common solution on the web side is to offset the application content by 20 pixels from the top to account for the status bar when the platform is detected as iOS7 using the Cordova Device Plugin.

Some UI frameworks like Ionic actually do this for you. They use the Cordova Device plugin (installed automatically when you create a new ionic project with the CLI) to detect the platform details and will apply different CSS classes to the navigation bars and other UI objects to handle things based on platform and OS versions.

There’s also a native solution available via the Cordova Status Bar plugin. This plugin is also used to alter the appearance of the status bar (color/style) from the native side so you can customize your applications to fit your specific needs.

Install the Plugin

To use the Status Bar plugin, first install it in the usual manner:

$ cordova plugin add org.apache.cordova.statusbar

Plugin (1)

Using the Cordova StatusBar Plugin

To Fix Overlap…

The StatusBar Plugin can be used to natively address the overlap issue by setting StatusBarOverlaysWebview preference to false in the config.xml or programmatically via the overlaysWebView() method.

If the overlay is found to be true, which it is by default as you’ll see below, the application will have the default iOS7 behavior where the transparent status bar is overlapping the application’s WebView. This is why you see it displayed this way without making any additional changes even after adding this plugin:

statusbar-problem

However it can be set to false to allow the status bar to have its own set space as in iOS6. Setting StatusBarOverlaysWebview to false also allows a color to be applied to the background as shown in black here:
statusbar-problem-fix

You can see in the snippets below how this is handled in the plugin Obj-C code if you’re curious. (I removed some pieces of code to keep it simpler for this post).

if (statusBarOverlaysWebView) {
       ...
       self.webView.frame = bounds;       
} else {
        ...
        CGRect statusBarFrame = [UIApplication sharedApplication].statusBarFrame;
        CGRect frame = self.webView.frame;
        frame.origin.y = statusBarFrame.size.height;
        frame.size.height -= statusBarFrame.size.height;  
        ...
        self.webView.frame = frame;        
}
To keep more of the iOS7 feel, set the background color of the status bar to match your application background color. See the next section for details.

Customizing via Configuration Settings

If you’re looking to control the status bar overlay value, color, or style you can do so by simply tweaking some configuration preferences for the Status Bar Plugin to use with no manual code required.

When the status bar plugin is added, preferences it uses for iOS are added into the ios platform config.xml automatically with the following values (see in your project path under myProj/platforms/ios/myProj/config.xml for instance):

   <preference name="StatusBarOverlaysWebView" value="true" /> 
   <preference name="StatusBarBackgroundColor" value="#000000" />
   <preference name="StatusBarStyle" value="lightcontent" />
If you didn’t add the plugin at all or customize anything on your status bar, the default foreground/text color is black and the default background color will be the color of your application’s background for iOS7 since it’s transparent. By just adding the plugin and doing nothing more however, you are already customizing it with the above preferences since they are added automatically, so you need to be aware of this.

To change the configuration preferences, be sure to first copy them into your root project config.xml (ie: myProj/config.xml) and tweak them there since the platform config files get rebuilt each time you build/run with the CLI and you will lose any changes made there. (You don’t need to copy the <feature> element lines for the plugin itself, just these preferences).

Setting Colors

  • StatusBarBackgroundColor sets the background color of the bar but ONLY when StatusBarOverlaysWebView is false
  • StatusBarStyle sets the foreground color, including the text and icons

Explanation
It may be confusing if you tried to run the application now with the status bar plugin and preferences added as above because you might expect to see a black background based on the preference set for StatusBarBackgroundColor to #000000. However, this preference is only used when the StatusBarOverlaysWebView is false. In other words, background color can only be set if it’s iOS6 style and not the iOS7 transparent overlay, but that setting is true initially so you’d have to change it to false yourself if you want to set a specific color.

Status Bar Styles

  • The default and blacktranslucent values display black foreground text and icons.
  • The lightcontent and blackopaque values display white foreground text and icons.

This setting is applied without regard to the status bar background color so if you accidentally pick the same color for both, you will not see any status bar, just a 20px white or black bar at the top of your application.

Also, the StatusBarStyle preference for text color is applied regardless of the StatusBarOverlaysWebView value since it just sets the text/foreground color and can be set on a transparent status bar.

It can be a little confusing to set this preference based on just looking at the available values compared to the results. Since both blacktranslucent and default display black text and both blackopaque and lightcontent display white text you may question when to use which or wonder what the difference is, the names make this a little more confusing still. It should help to know these values map directly to the native Apple values for the UIStatusBarStyle and the blacktranslucent and blackopaque were deprecated in iOS7 but the plugin options are still available to maintain backwards compatibility.

Tip: Stick with using default for black text and lightcontent for white text to avoid further confusion.

Use the Status Bar Simulator App

Now that you understand the options more thoroughly, click here to go back to the Status Bar Simulator app to try different combinations of settings and see the results. When you find the combination that works just copy and paste the generated settings directly into your *root* project config.xml. I only included a small set of colors so if you like something else you’ll need to change that hex value, but that should be fairly obvious.

The initial values for the preferences in the demo app were set to those defaults added by the StatusBar plugin so you see what you’re getting by making no change. Remember, the StatusBarBackgroundColor is disabled since the StatusBarOverlaysWebView value is true and color doesn’t apply unless it’s false.

Also, the demo doesn’t use any specific UI frameworks, it’s just a modified default Cordova Hello World.

Customizing Programmatically

The other option for using the Status Bar plugin is to programmatically set the desired overlay and appearance of your application and show or hide it at runtime using the plugins’ API methods. These methods are pretty straightforward and documented well in the plugin readme but I just wanted to point out these programmatic options as well.

ATTENTION IONIC USERS: If you’re building apps with Ionic and add the StatusBar Plugin, you should be aware that all of their default templates that can be created with CLI $ ionic start include code that sets the default style (black text) programmatically upon application start in the www/js/app.js file in each project:

if(window.StatusBar) {
  // org.apache.cordova.statusbar required
  StatusBar.styleDefault();
}

so your config.xml settings will be overridden unless you remove this. You may wonder why they’re not being applied otherwise :). See this article for how to programmatically customize the status bar with Ionic.

Related Reading

Filed in: CordovaiOSMobile DevelopmentPhoneGap Tags:

About the Author ()

Comments (7)

Trackback URL | Comments RSS Feed

  1. Luane says:

    Thank you for this! I was just doing some work on the iOS status bar last month and this would have helped a lot! :)

  2. Barry Baker says:

    This is a fantastic article. The status bar in iOS 7+ has always been very difficult to deal with, but your article has explained everything very comprehensively. The interactive simulator app will definitely come in handy. Thanks Holly!

  3. Carl says:

    This is a great guide that makes up for the lack of decent documentation elsewhere. Unfortunately for me I’ve been using PhoneGap Build :-(

    I’ve tried adding the status bar plugin to the config.xml

    gap:plugin name=”com.phonegap.plugin.statusbar”

    followed by some basic settings (again within config.xml) such as:

    preference name=”StatusBarOverlaysWebView” value=”false”
    preference name=”StatusBarBackgroundColor” value=”#000000″
    preference name=”StatusBarStyle” value=”lightcontent”

    However, PhoneGap Build doesn’t seem to like this and all I ever see is a blank black status bar. Has anyone managed to crack this one? I’ve yet to find a simple clear solution.

  4. kian says:

    Hi, thank you for your useful tutorial
    I’m Kian a chemistry teacher. I created some android apps, most of my apps are about chemistry, you can see my apps screen shots in http://www.kiandroid.ir
    I’m trying to learn phonegap I want a phonegap sample that I import in eclipse and see how it works, I will be thankful if you send me a simple project in my Email addresses, if it is possible of course.

  5. Timothy Nott says:

    I truly wish I had read this at some point early last week. Would have saved me from at least one aspect of this debacle. Great stuff!

  6. Ed says:

    Great article!

    Just wondering how you created the iPhone simulator used in this post?

    When running Ionic apps in the browser the native features like status bar don’t work, so I was just wondering how you did it for this article?

    Thanks

  7. @ksgsloan says:

    awesome write up, thanks!

Leave a Reply