@capawesome/capacitor-screen-orientation

Capacitor plugin to lock/unlock the screen orientation.

Features

We are proud to offer one of the most complete and feature-rich Capacitor plugins for screen orientation control. Here are some of the key features:

- 🖥️ Cross-platform: Supports Android, iOS, and Web.
- 🔒 Orientation locking: Lock screen to specific orientations.
- 🔓 Orientation unlocking: Unlock and restore automatic orientation.
- 📱 Multiple orientations: Support for portrait, landscape, and specific orientations.
- 🔄 Orientation detection: Get current screen orientation.
- 📢 Event listeners: Listen to orientation change events.
- 📐 Fine-grained control: Primary and secondary orientation modes.
- 🍎 iPad support: Special configuration for iPad orientation locking.
- 🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Compatibility

| Plugin Version | Capacitor Version | Status |
| -------------- | ----------------- | -------------- |
| 8.x.x | >=8.x.x | Active support |
| 7.x.x | 7.x.x | Deprecated |
| 6.x.x | 6.x.x | Deprecated |
| 5.x.x | 5.x.x | Deprecated |

Installation

``bash
npm install @capawesome/capacitor-screen-orientation
npx cap sync
`

$3

#### General

On iOS you must add the following to your app's AppDelegate.swift:

`diff
+ import CapawesomeCapacitorScreenOrientation

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

+ func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
+ return ScreenOrientation.getSupportedInterfaceOrientations()
+ }
`

#### iPad Orientation Lock

On iPad, you must add the following to your app's Info.plist:

`xml
UIRequiresFullScreen

`

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-plugin-demo

Usage

`typescript
import { ScreenOrientation, OrientationType } from '@capawesome/capacitor-screen-orientation';

const lock = async () => {
await ScreenOrientation.lock({ type: OrientationType.LANDSCAPE });
};

const unlock = async () => {
await ScreenOrientation.unlock();
};

const getCurrentOrientation = async () => {
const result = await ScreenOrientation.getCurrentOrientation();
return result.type;
};
`

API

* lock(...)
* unlock()
* getCurrentOrientation()
* addListener('screenOrientationChange', ...)
* removeAllListeners()
* Interfaces
* Type Aliases
* Enums

$3

`typescript
lock(options?: LockOptions | undefined) => Promise
`

Locks the device orientation.

| Param | Type |
| ------------- | --------------------------------------------------- |
| options | LockOptions |

--------------------

$3

`typescript
unlock() => Promise
`

Unlocks the device orientation.

--------------------

$3

`typescript
getCurrentOrientation() => Promise
`

Gets the current device orientation type.

Returns: Promise<GetCurrentOrientationResult>

--------------------

$3

`typescript
addListener(eventName: 'screenOrientationChange', listenerFunc: ScreenOrientationChangeListener) => Promise
`

Listen for screen orientation changes.

| Param | Type |
| ------------------ | ------------------------------------------------------------------------------------------- |
| eventName | 'screenOrientationChange' |
| listenerFunc | ScreenOrientationChangeListener |

Returns: Promise<PluginListenerHandle>

--------------------

$3

`typescript
removeAllListeners() => Promise
`

Remove all listeners for this plugin.

--------------------

$3


#### LockOptions

| Prop | Type | Description |
| ---------- | ----------------------------------------------------------- | -------------------------- |
| type | OrientationType | The orientation lock type. |


#### GetCurrentOrientationResult

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


#### PluginListenerHandle

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


#### ScreenOrientationChange

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

$3


#### ScreenOrientationChangeListener

Callback to receive the screen orientation change notifications.

(change: ScreenOrientationChange): void

$3


#### OrientationType

| Members | Value | Description |
| ------------------------- | ---------------------------------- | ------------------------------------------------------------------- |
| LANDSCAPE | 'landscape' | The orientation is either landscape-primary or landscape-secondary. |
| LANDSCAPE_PRIMARY | 'landscape-primary' | The orientation is in the primary landscape mode. |
| LANDSCAPE_SECONDARY | 'landscape-secondary' | The orientation is in the secondary landscape mode. |
| PORTRAIT | 'portrait' | The orientation is either portrait-primary or portrait-secondary. |
| PORTRAIT_PRIMARY | 'portrait-primary' | The orientation is in the primary portrait mode. |
| PORTRAIT_SECONDARY` | 'portrait-secondary' | The orientation is in the secondary portrait mode. |

Changelog

See CHANGELOG.md.

License

See LICENSE.

Credits

This plugin is based on the Capacitor Screen Orientation plugin.
Thanks to everyone who contributed to the project!