Skip to main content

cordova-plugin-screen-orientation Alternative for Capacitor

cordova-plugin-screen-orientation alternative for Capacitor: lock and unlock orientation with @capgo/capacitor-screen-orientation, motion tracking, and foldable APIs.

Illustration of migrating a Cordova app to Capacitor, used for a screen orientation plugin guide

The practical cordova-plugin-screen-orientation alternative for a Capacitor app is @capgo/capacitor-screen-orientation. It maps the Cordova window.screen.orientation lock and unlock calls to typed ScreenOrientation promises, adds isOrientationLocked() and foldable helpers from definitions.ts, and removes the Cordova exec bridge. This guide lists npm facts, install steps, usage, and an API map for your Cordova to Capacitor move.

Why leave cordova-plugin-screen-orientation in Capacitor

cordova-plugin-screen-orientation on npm is version 3.0.4. The registry modified timestamp is 5 November 2023. The source lives at apache/cordova-plugin-screen-orientation. The README documents these window.screen.orientation APIs from www/screenorientation.js:

  • screen.orientation.lock(orientation) returns a Promise
  • screen.orientation.unlock()
  • screen.orientation for the current orientation value
  • screen.orientation.onchange listener support

Supported lock strings match the W3C Screen Orientation API: portrait-primary, portrait-secondary, landscape-primary, landscape-secondary, combined portrait and landscape, and any.

In a Capacitor codebase the Cordova plugin still means a global screen.orientation shim installed through cordova plugin add, with no TypeScript surface and no foldable or motion sensor helpers.

@capgo/capacitor-screen-orientation latest on npm is 8.4.5 with a modified date of 12 November 2026. src/definitions.ts documents lock(), unlock(), orientation(), isOrientationLocked(), addListener('screenOrientationChange'), and optional bypassOrientationLock on OrientationLockOptions. Capgo ships fixes on an open source cadence where a human still reviews, tests and merges 50+ pull requests daily.

Install

bun add @capgo/capacitor-screen-orientation
bunx cap sync

Match your Android AndroidManifest.xml activity screenOrientation defaults to your lock policy. The Cordova plugin historically relied on config.xml orientation preferences; set the same values in native projects or lock at runtime from JavaScript.

Usage example

import { ScreenOrientation } from '@capgo/capacitor-screen-orientation';

export async function lockGameLandscape() {
  const handle = await ScreenOrientation.addListener('screenOrientationChange', ({ type }) => {
    console.log('orientation', type);
  });

  await ScreenOrientation.lock({ orientation: 'landscape' });
  const { type } = await ScreenOrientation.orientation();
  console.log('current', type);

  // Later
  await ScreenOrientation.unlock();
  await handle.remove();
}

Migrating from Cordova to Capacitor

// Before (Cordova)
await screen.orientation.lock('portrait');
screen.orientation.unlock();
// After (Capacitor)
import { ScreenOrientation } from '@capgo/capacitor-screen-orientation';

await ScreenOrientation.lock({ orientation: 'portrait' });
await ScreenOrientation.unlock();

API mapping table

cordova-plugin-screen-orientation (screen.orientation) @capgo/capacitor-screen-orientation
lock('portrait-primary') etc. lock({ orientation: 'portrait-primary' })
unlock() unlock()
screen.orientation value orientation() returns { type }
screen.orientation.onchange addListener('screenOrientationChange', ...)
Not in Cordova www isOrientationLocked() with physical vs UI orientation
Not in Cordova www startOrientationTracking() / stopOrientationTracking() when bypassOrientationLock is needed for events only
Cordova plugin install bun add @capgo/capacitor-screen-orientation plus bunx cap sync

Orientation locks ship in the native binary, so plan a store build after you swap plugins. Use Capgo Build for cloud builds, then ship UI logic with Capgo live updates only where orientation handling stays in JavaScript. For the full platform move, read the Cordova to Capacitor migration guide.

Live updates for Capacitor apps

When a web-layer bug is live, ship the fix through Capgo instead of waiting days for app store approval. Users get the update in the background while native changes stay in the normal review path.

Latest from our Blog

Capgo gives you the best insights you need to create a truly professional mobile app.