Screen Orientation Capacitor plugin

Using @capgo/capacitor-screen-orientation

Capacitor Screen Orientation Plugin interface.

Install

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

bunx cap sync copies the plugin's native code into your native projects. Run it again after every plugin upgrade.

Import

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

API at a glance

Examples

orientation()

Get the current screen orientation.

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

const result = await ScreenOrientation.orientation();
console.log('Current orientation:', result.type);

lock()

Lock the screen orientation to a specific type.

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

// Standard lock
await ScreenOrientation.lock({ orientation: 'landscape' });

// Lock with motion tracking on iOS
await ScreenOrientation.lock({
  orientation: 'portrait',
  bypassOrientationLock: true
});

unlock()

Unlock the screen orientation.

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

await ScreenOrientation.unlock();

startOrientationTracking()

Start tracking device orientation using motion sensors.

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

await ScreenOrientation.startOrientationTracking({
  bypassOrientationLock: true
});

// Listen for changes
ScreenOrientation.addListener('screenOrientationChange', (result) => {
  console.log('Orientation changed:', result.type);
});

stopOrientationTracking()

Stop tracking device orientation using motion sensors.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked()

Check if device orientation lock is currently enabled.

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

// Start motion tracking first
await ScreenOrientation.startOrientationTracking({
  bypassOrientationLock: true
});

// Check lock status
const status = await ScreenOrientation.isOrientationLocked();
if (status.locked) {
  console.log('Orientation lock is ON');
  console.log('Physical:', status.physicalOrientation);
  console.log('UI:', status.uiOrientation);
}

The table above lists the 13 core methods. Listener and version helpers, and the full contract of each method, are documented in the GitHub repository.

Listen to events

addListener returns a handle. Call handle.remove() when the screen unmounts, or ScreenOrientation.removeAllListeners() to clear every listener.

Full reference

• GitHub repository
• Documentation
• API reference

Keep going from Using @capgo/capacitor-screen-orientation

If you are using Using @capgo/capacitor-screen-orientation to plan native media and interface behavior, connect it with @capgo/capacitor-screen-orientation for the implementation detail in @capgo/capacitor-screen-orientation, Getting Started for the implementation detail in Getting Started, Using @capgo/capacitor-live-activities for the native capability in Using @capgo/capacitor-live-activities, @capgo/capacitor-live-activities for the implementation detail in @capgo/capacitor-live-activities, and Using @capgo/capacitor-video-player for the native capability in Using @capgo/capacitor-video-player.