Screen Orientation

cordova-plugin-screen-orientation

iOS Android 🌐 Browser

This Apache Cordova plugin lets you lock the screen to a specific orientation, release it back to the device's automatic rotation, and read the current orientation. It builds on the standard screen.orientation Web API, so the code looks familiar.

Installation

terminal

cordova plugin add cordova-plugin-screen-orientation

API

The plugin extends the global screen.orientation object. Use it after deviceready:

Member	Description
`screen.orientation.lock(orientation)`	Lock to an orientation; returns a Promise.
`screen.orientation.unlock()`	Release the lock and allow automatic rotation.
`screen.orientation.type`	The current orientation string (read-only).
`screen.orientation.angle`	The current rotation angle in degrees (read-only).
`screen.orientation.onchange`	Handler fired when the orientation changes.

Orientation values

Pass one of these strings to lock(): portrait-primary, portrait-secondary, landscape-primary, landscape-secondary, portrait, landscape or any.

Usage example

Force landscape for a video screen, then restore rotation when leaving:

www/js/app.js

function enterPlayer() {
  screen.orientation.lock("landscape");

  screen.orientation.addEventListener("change", function () {
    console.log("Now: " + screen.orientation.type);
  });
}

function leavePlayer() {
  screen.orientation.unlock();
}

Tips

Always unlock() when leaving a locked screen, or the rest of your app stays stuck.
Locking may reject if the OS can't honour it (for example on some tablets) — handle the Promise rejection.
Read screen.orientation.type to adapt layout rather than guessing from window size.

📚 Source: the technical reference on this page is based on the cordova-plugin-screen-orientation project, maintained by the Apache Cordova community, and the standard Screen Orientation Web API. Descriptions and examples have been rewritten in DedrisFramework's own words.

← Back to plugins Start a project