@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.

Installation

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

iOS

General

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

+ 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:

<key>UIRequiresFullScreen</key>
<true/>

Configuration

No configuration required for this plugin.

Demo

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

Usage

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

lock(...)

lock(options?: LockOptions | undefined) => Promise<void>

Locks the device orientation.

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

unlock()

unlock() => Promise<void>

Unlocks the device orientation.

getCurrentOrientation()

getCurrentOrientation() => Promise<GetCurrentOrientationResult>

Gets the current device orientation type.

Returns: Promise<GetCurrentOrientationResult>

addListener('screenOrientationChange', ...)

addListener(eventName: 'screenOrientationChange', listenerFunc: ScreenOrientationChangeListener) => Promise<PluginListenerHandle>

Listen for screen orientation changes.

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

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Interfaces

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. |

Type Aliases

ScreenOrientationChangeListener

Callback to receive the screen orientation change notifications.

(change: ScreenOrientationChange): void

Enums

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!