Introduction

When iOS 7 changed the visual treatment of the status bar, many PhoneGap applications suddenly had content rendering underneath it. The fix was not a single magic setting. You had to decide whether the web view should extend under the bar and then configure the Cordova status bar plugin, app preferences, and page layout consistently.

Understand what changed in iOS 7

Before iOS 7, hybrid apps often behaved as if the status bar sat above the web content. With iOS 7, the bar became visually integrated with the application, and the web view could extend beneath it. That made layouts look modern, but it also meant headers, buttons, and title text could end up hidden at the top of the screen.

In PhoneGap, this was mostly a layout and configuration problem. The app was still running, but the HTML and CSS needed to account for the new top inset behavior.

Install and use the status bar plugin

Cordova applications control the status bar through cordova-plugin-statusbar. After the plugin is installed, call its API only after the deviceready event fires.

cordova plugin add cordova-plugin-statusbar

1document.addEventListener("deviceready", onReady, false);
2
3function onReady() {
4  StatusBar.styleDefault();
5  StatusBar.overlaysWebView(false);
6  StatusBar.backgroundColorByHexString("#1f6f8b");
7}

StatusBar.overlaysWebView(false) is the critical line when your content is sliding under the bar and you want the web view pushed below it instead.

Coordinate plugin settings with config.xml

Some teams prefer to keep status bar behavior in application configuration so the startup behavior is predictable.

1<widget id="com.example.app" version="1.0.0" xmlns="http://www.w3.org/ns/widgets">
2  <preference name="StatusBarOverlaysWebView" value="false" />
3  <preference name="StatusBarBackgroundColor" value="#1f6f8b" />
4</widget>

Setting the preference and calling the API are not competing ideas. It is common to use config.xml for the default startup state and JavaScript when a specific screen needs different behavior.

Fix the layout in CSS as well

The plugin only controls native behavior. Your HTML still needs spacing that makes sense visually. If you leave a custom header at top: 0 while also changing overlay behavior, the result can still look wrong.

1body {
2  margin: 0;
3  font-family: Helvetica, Arial, sans-serif;
4}
5
6.app-header {
7  background: #1f6f8b;
8  color: white;
9  padding: 16px;
10}
11
12.content {
13  padding: 16px;
14}

If you intentionally keep the web view under the status bar, add top padding to the first visible element so important controls are not obscured.

Choose between overlay and non-overlay deliberately

There are two valid layouts:

• Overlay mode, where the app extends under the status bar for a more immersive look.
• Non-overlay mode, where the native view starts below the bar and your HTML never sits underneath it.

For older PhoneGap projects targeting iOS 7, non-overlay mode was often the quickest fix because it restored a more familiar layout. Overlay mode looked better when the design was built around it, but it required more careful CSS.

Handle text color and background together

Status bar readability depends on contrast. A dark header usually needs light status bar content, while a light header needs dark content. If the text color and background color do not match, the app can look broken even if the layout is technically correct.

1document.addEventListener("deviceready", function () {
2  StatusBar.styleLightContent();
3  StatusBar.backgroundColorByHexString("#1f6f8b");
4}, false);

Use one consistent visual choice per screen. Randomly changing status bar color without updating the header usually makes the hybrid shell feel unpolished.

Common Pitfalls

• Calling StatusBar methods before deviceready, which means the plugin is not ready yet.
• Setting overlay behavior in code but forgetting conflicting defaults in config.xml.
• Fixing the native status bar and forgetting to add matching CSS spacing in the page.
• Choosing a background color and text style combination with poor contrast.
• Assuming the issue is PhoneGap-only when the real problem is a header layout that ignores top inset behavior.

Summary

• iOS 7 changed status bar behavior in a way that affected many PhoneGap layouts.
• Use cordova-plugin-statusbar to control overlay, style, and background color.
• 'StatusBar.overlaysWebView(false) is the common fix when content is hidden under the bar.'
• Keep config.xml, JavaScript, and CSS aligned so the layout is predictable.
• Treat the status bar as part of the screen design, not as a separate afterthought.