@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¶
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
:
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(...)¶
Locks the device orientation.
Param | Type |
---|---|
options |
LockOptions |
unlock()¶
Unlocks the device orientation.
getCurrentOrientation()¶
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()¶
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!