https://github.com/Cap-go/capacitor-screen-orientation
Capacitor plugin for screen orientation with support for detecting true physical device orientation
https://github.com/Cap-go/capacitor-screen-orientation
capacitor capacitor-plugin
Last synced: about 1 month ago
JSON representation
Capacitor plugin for screen orientation with support for detecting true physical device orientation
- Host: GitHub
- URL: https://github.com/Cap-go/capacitor-screen-orientation
- Owner: Cap-go
- License: mpl-2.0
- Created: 2025-11-28T15:37:04.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-01-28T17:41:49.000Z (about 1 month ago)
- Last Synced: 2026-01-29T07:47:58.296Z (about 1 month ago)
- Topics: capacitor, capacitor-plugin
- Language: Swift
- Homepage: https://capgo.app/?ref=plugin_screen_orientation
- Size: 524 KB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-capacitor - Screen Orientation - Control device orientation with support for bypassing orientation lock. ([Capgo plugins](https://capgo.app/) / UI & Display)
README
# @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/
## Compatibility
| Plugin version | Capacitor compatibility | Maintained |
| -------------- | ----------------------- | ---------- |
| v8.\*.\* | v8.\*.\* | ✅ |
| v7.\*.\* | v7.\*.\* | On demand |
| v6.\*.\* | v6.\*.\* | ❌ |
| v5.\*.\* | v5.\*.\* | ❌ |
> **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
## Install
```bash
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`:
```xml
NSMotionUsageDescription
This app uses motion sensors to detect the true physical orientation of your device.
```
## Usage
```typescript
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()`](#orientation)
* [`lock(...)`](#lock)
* [`unlock()`](#unlock)
* [`startOrientationTracking(...)`](#startorientationtracking)
* [`stopOrientationTracking()`](#stoporientationtracking)
* [`isOrientationLocked()`](#isorientationlocked)
* [`addListener('screenOrientationChange', ...)`](#addlistenerscreenorientationchange-)
* [`removeAllListeners()`](#removealllisteners)
* [`getPluginVersion()`](#getpluginversion)
* [Interfaces](#interfaces)
* [Type Aliases](#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()
```typescript
orientation() => Promise
```
Get the current screen orientation.
Returns the current orientation of the device screen.
**Returns:** Promise<ScreenOrientationResult>
**Since:** 1.0.0
--------------------
### lock(...)
```typescript
lock(options: OrientationLockOptions) => Promise
```
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()
```typescript
unlock() => Promise
```
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(...)
```typescript
startOrientationTracking(options?: StartOrientationTrackingOptions | undefined) => Promise
```
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()
```typescript
stopOrientationTracking() => Promise
```
Stop tracking device orientation using motion sensors.
Stops the motion-based orientation tracking if it was started.
**Since:** 1.0.0
--------------------
### isOrientationLocked()
```typescript
isOrientationLocked() => Promise
```
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', ...)
```typescript
addListener(eventName: 'screenOrientationChange', listenerFunc: (result: ScreenOrientationResult) => void) => Promise
```
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()
```typescript
removeAllListeners() => Promise
```
Remove all listeners for this plugin.
Removes all registered event listeners.
**Since:** 1.0.0
--------------------
### getPluginVersion()
```typescript
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'