Skip to main content
Version: v5

@capacitor/screen-orientation

The Screen Orientation API provides information and functionality related to the orientation of the screen.

Installโ€‹

npm install @capacitor/screen-orientation@latest-5
npx cap sync

iOSโ€‹

Locking the Screen Orientation only works for the Capacitor View Controller only, but not other View Controllers being presented (such as the one presented by Browser plugin). For also lock presented View Controllers, this code can be added to the app's AppDelegate.swift file:

func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
return UIInterfaceOrientationMask(rawValue: (self.window!.rootViewController as! CAPBridgeViewController).supportedInterfaceOrientations.rawValue)
}

iPad Orientation Lockโ€‹

By default, an iPad allows Multitasking and its orientation cannot be locked. If you need to lock orientation on an iPad set the option Requires Full Screen to YES by adding the following to Info.plist:

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

APIโ€‹

orientation()โ€‹

orientation() => Promise<ScreenOrientationResult>

Returns the current screen orientation.

Returns:

Promise<ScreenOrientationResult>

Since: 4.0.0


lock(...)โ€‹

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

Locks the screen orientation.

ParamType
options
OrientationLockOptions

Since: 4.0.0


unlock()โ€‹

unlock() => Promise<void>

Unlocks the screen's orientation.

Since: 4.0.0


addListener('screenOrientationChange', ...)โ€‹

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

Listens for screen orientation changes.

ParamType
eventName'screenOrientationChange'
listenerFunc
(orientation: ScreenOrientationResult) => void

Returns:

Promise<PluginListenerHandle> & PluginListenerHandle

Since: 4.0.0


removeAllListeners()โ€‹

removeAllListeners() => Promise<void>

Removes all listeners.

Since: 4.0.0


Interfacesโ€‹

ScreenOrientationResultโ€‹

PropType
typeOrientationType

OrientationLockOptionsโ€‹

PropTypeDescription
orientation
OrientationLockType
Note: Typescript v5.2+ users should import OrientationLockType from @capacitor/screen-orientation.

PluginListenerHandleโ€‹

PropType
remove() => Promise<void>

Type Aliasesโ€‹

OrientationLockTypeโ€‹

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