@capgo/capacitor-screen-orientation

Screen orientation plugin with support for detecting true physical device orientation

Features

• 📱 Full Screen Orientation API support
• 🔍 Detect true physical device orientation using motion sensors (even when orientation lock is enabled)
  • iOS: Uses Core Motion framework
  • Android: Uses accelerometer sensor
• 🔒 Detect if orientation lock is enabled by comparing physical vs UI orientation
• 🔄 Real-time orientation change detection
• 🎯 Lock orientation to specific modes
• 🌐 Web platform support

Important Note: This plugin can detect the physical orientation of the device using motion sensors, but it cannot bypass the UI orientation lock. The screen will still respect the user's orientation lock setting. This is useful for knowing how the device is physically held vs. how the UI is displayed.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/screen-orientation/

Install

npm install @capgo/capacitor-screen-orientation
npx cap sync

iOS Configuration

To detect physical device orientation using motion sensors on iOS, you need to add the Motion Usage Description to your Info.plist:

<key>NSMotionUsageDescription</key>
<string>This app uses motion sensors to detect the true physical orientation of your device.</string>

Usage

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

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

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

// Lock UI orientation and track physical orientation via motion sensors
// Note: UI will still respect user's orientation lock, but you'll get physical orientation events
await ScreenOrientation.lock({
  orientation: 'portrait',
  bypassOrientationLock: true
});

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

// Unlock orientation
await ScreenOrientation.unlock();

// Start motion-based tracking to detect physical device orientation
// This uses motion sensors to track how the device is actually held
await ScreenOrientation.startOrientationTracking({
  bypassOrientationLock: true
});

// Check if device orientation lock is enabled
// Compares physical device orientation (from sensors) with UI orientation (from system)
const lockStatus = await ScreenOrientation.isOrientationLocked();
if (lockStatus.locked) {
  console.log('Orientation lock is ON!');
  console.log('Physical device orientation:', lockStatus.physicalOrientation);
  console.log('UI orientation:', lockStatus.uiOrientation);
} else {
  console.log('Orientation lock is OFF or motion tracking not active');
}

// Stop motion-based tracking
await ScreenOrientation.stopOrientationTracking();

// Remove listener
await listener.remove();

API

• orientation()
• lock(...)
• unlock()
• startOrientationTracking(...)
• stopOrientationTracking()
• isOrientationLocked()
• addListener('screenOrientationChange', ...)
• removeAllListeners()
• getPluginVersion()
• Interfaces
• Type Aliases

Capacitor Screen Orientation Plugin interface.

Provides methods to detect and control screen orientation, with support for detecting true physical device orientation using motion sensors.

orientation()

orientation() => Promise<ScreenOrientationResult>

Get the current screen orientation.

Returns the current orientation of the device screen.

Returns: Promise<ScreenOrientationResult>

Since: 1.0.0

lock(...)

lock(options: OrientationLockOptions) => Promise<void>

Lock the screen orientation to a specific type.

Locks the screen to the specified orientation. On iOS, if bypassOrientationLock is true, it will also start tracking physical device orientation using motion sensors.

Note: The UI will still respect the user's orientation lock setting. Motion tracking allows you to detect how the device is physically held even when the UI doesn't rotate.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | ------------------------------------ | | options | OrientationLockOptions | Options for locking the orientation. |

Since: 1.0.0

unlock()

unlock() => Promise<void>

Unlock the screen orientation.

Allows the screen to rotate freely based on device position. Also stops any motion-based orientation tracking if it was enabled.

Since: 1.0.0

startOrientationTracking(...)

startOrientationTracking(options?: StartOrientationTrackingOptions | undefined) => Promise<void>

Start tracking device orientation using motion sensors.

This method is useful when you want to track the device's physical orientation independently from the screen orientation lock. It uses Core Motion on iOS to detect orientation changes.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------ | | options | StartOrientationTrackingOptions | Options for starting orientation tracking. |

Since: 1.0.0

stopOrientationTracking()

stopOrientationTracking() => Promise<void>

Stop tracking device orientation using motion sensors.

Stops the motion-based orientation tracking if it was started.

Since: 1.0.0

isOrientationLocked()

isOrientationLocked() => Promise<OrientationLockStatusResult>

Check if device orientation lock is currently enabled.

This method compares the physical device orientation (from motion sensors) with the UI orientation. If they differ, orientation lock is enabled.

Note: This requires motion tracking to be active via startOrientationTracking() or lock() with bypassOrientationLock: true. Works on both iOS (Core Motion) and Android (Accelerometer).

Returns: Promise<OrientationLockStatusResult>

Since: 1.0.0

addListener('screenOrientationChange', ...)

addListener(eventName: 'screenOrientationChange', listenerFunc: (result: ScreenOrientationResult) => void) => Promise<PluginListenerHandle>

Listen for screen orientation changes.

Registers a listener that will be called whenever the screen orientation changes. If motion-based tracking is enabled, this will also fire for orientation changes detected by motion sensors even when orientation lock is enabled.

| Param | Type | Description | | ------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------------------------- | | eventName | 'screenOrientationChange' | The event name. Must be 'screenOrientationChange'. | | listenerFunc | (result: ScreenOrientationResult) => void | Callback function invoked when orientation changes. |

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Removes all registered event listeners.

Since: 1.0.0

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native plugin version.

Returns the current version of the native plugin implementation.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Interfaces

ScreenOrientationResult

Result returned by the orientation() method.

| Prop | Type | Description | Since | | ---------- | ----------------------------------------------------------- | ----------------------------- | ----- | | type | OrientationType | The current orientation type. | 1.0.0 |

OrientationLockOptions

Options for locking the screen orientation.

| Prop | Type | Description | Default | Since | | --------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | | orientation | OrientationLockType | The orientation type to lock to. | | 1.0.0 | | bypassOrientationLock | boolean | Whether to track physical device orientation using motion sensors. When true, uses device motion sensors to detect the true physical orientation of the device, even when the device orientation lock is enabled. Important: This does NOT bypass the UI orientation lock. The screen will still respect the user's orientation lock setting. This option only affects orientation detection/tracking - you'll receive orientation change events based on how the device is physically held, but the UI will not rotate if orientation lock is enabled. Supported on iOS (Core Motion) and Android (Accelerometer). | false | 1.0.0 |

StartOrientationTrackingOptions

Options for starting orientation tracking using motion sensors.

| Prop | Type | Description | Default | Since | | --------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | | bypassOrientationLock | boolean | Whether to track physical device orientation using motion sensors. When true, uses device motion sensors to detect the true physical orientation of the device, even when the device orientation lock is enabled. Important: This does NOT bypass the UI orientation lock. This only enables detection of the physical orientation. Supported on iOS (Core Motion) and Android (Accelerometer). | false | 1.0.0 |

OrientationLockStatusResult

Result returned by the isOrientationLocked() method.

| Prop | Type | Description | Since | | ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | locked | boolean | Whether the device orientation lock is currently enabled. This is determined by comparing the physical device orientation (from motion sensors) with the UI orientation. If they differ, orientation lock is enabled. Available on iOS (Core Motion) and Android (Accelerometer) when motion tracking is active. | 1.0.0 | | physicalOrientation | OrientationType | The physical orientation of the device from motion sensors. Available when motion tracking is active (iOS and Android). | 1.0.0 | | uiOrientation | OrientationType | The current UI orientation reported by the system. | 1.0.0 |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

Type Aliases

OrientationType

Orientation type that describes the orientation state of the device.

'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary'

OrientationLockType

Orientation lock type that can be used to lock the device orientation.

'any' | 'natural' | 'landscape' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary'