Introduction

In a PhoneGap or Cordova app, orientation changes are detected from the WebView side, not from UIKit directly. On iOS, the basic event is easy to register, but the tricky part is timing: the event can fire before layout values fully settle, so robust code often reacts to the event and then reads dimensions after the WebView has updated.

Listen After deviceready

In hybrid apps, do not attach your orientation logic too early. Wait for deviceready, then bind the handler:

1document.addEventListener("deviceready", function () {
2  window.addEventListener("orientationchange", onOrientationChange, false);
3}, false);
4
5function onOrientationChange() {
6  console.log("orientation changed");
7  console.log("angle:", window.orientation);
8}

This is the traditional PhoneGap pattern and works well as a starting point.

However, window.orientation alone is not a complete solution. It tells you the rotation angle, but it does not guarantee that the DOM layout, viewport size, and rendered coordinates are already stable.

Read Layout After the WebView Settles

A common iOS problem is that the orientation event fires, but window.innerWidth and window.innerHeight still reflect the old layout for a brief moment.

A safer pattern is to defer layout-dependent work:

1document.addEventListener("deviceready", function () {
2  window.addEventListener("orientationchange", updateLayout, false);
3  window.addEventListener("resize", updateLayout, false);
4}, false);
5
6function updateLayout() {
7  setTimeout(function () {
8    var isLandscape = window.innerWidth > window.innerHeight;
9    console.log("landscape:", isLandscape);
10    console.log("width:", window.innerWidth);
11    console.log("height:", window.innerHeight);
12  }, 0);
13}

Using resize as a companion event is helpful because some layout changes are better observed through the viewport dimensions than through the rotation angle itself.

Prefer Dimensions Over Raw Orientation Values for Layout Logic

If your real goal is “switch the UI when the app becomes landscape,” checking dimensions is often more reliable than branching on window.orientation values such as 0, 90, -90, or 180.

For example:

function isLandscape() {
  return window.innerWidth > window.innerHeight;
}

That avoids brittle device-specific assumptions and focuses on the layout condition your UI actually cares about.

You can still log or store the raw orientation value if you need analytics or device-state debugging, but layout decisions are usually cleaner when based on width and height.

When a Plugin Makes More Sense

If the app needs to lock orientation or reason about it in a more structured way, the Cordova screen-orientation plugin is often a better fit than ad hoc event handling. It gives you a clearer API for orientation state and locking behavior.

Even then, event timing still matters. Locking orientation and measuring rendered size are related concerns, but they are not identical.

Testing Advice for iOS Hybrid Apps

Orientation handling in a hybrid iOS app should be tested on actual devices and on the iOS versions you support. Simulator behavior is useful, but WebView timing, status-bar behavior, and layout updates can feel different on hardware.

Also verify the surrounding app configuration:

• supported interface orientations in the app settings
• any CSS media queries tied to width or orientation
• whether your code is trying to do layout work too early in the event

Many “orientation detection bugs” are really layout timing bugs.

Common Pitfalls

The biggest mistake is relying only on window.orientation and assuming the DOM has already reflowed. On iOS, those are not always synchronized the way you expect.

Another issue is binding the handler before deviceready, especially in older PhoneGap codebases where plugin and WebView initialization timing matters.

Developers also sometimes listen only for orientationchange when the real condition they care about is viewport resize. In hybrid apps, those are related but not identical.

Finally, avoid hard-coding one device’s angle behavior and assuming it generalizes cleanly across every iPhone and iPad context. Measure the layout state you actually need.

Summary

• Register orientation logic after deviceready in PhoneGap or Cordova.
• Use orientationchange to detect rotation, but use viewport dimensions for layout decisions.
• On iOS, defer layout-dependent work until the WebView has settled.
• Combine orientationchange and resize when the UI depends on actual rendered dimensions.
• Test on real devices because timing issues often appear there first.