Reference version

SDK 52

Archive Expo Snack Discord and Forums Newsletter

Expo ScreenOrientation

GitHub

npm

A universal library for managing a device's screen orientation.

Android

iOS

Web

Screen Orientation is defined as the orientation in which graphics are painted on the device. For example, the figure below has a device in a vertical and horizontal physical orientation, but a portrait screen orientation. For physical device orientation, see the orientation section of Device Motion.

Portrait orientation in different physical orientations.

On both Android and iOS platforms, changes to the screen orientation will override any system settings or user preferences. On Android, it is possible to change the screen orientation while taking the user's preferred orientation into account. On iOS, user and system settings are not accessible by the application and any changes to the screen orientation will override existing settings.

Web has limited support.

Installation

Terminal

- npx expo install expo-screen-orientation

If you are installing this in an existing React Native app, start by installing expo in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.

Warning

Apple added support for split view mode to iPads in iOS 9. This changed how the screen orientation is handled by the system. To put the matter shortly, for iOS, your iPad is always in landscape mode unless you open two applications side by side. To be able to lock screen orientation using this module you will need to disable support for this feature. For more information about the split view mode, check out the official Apple documentation.

Configuration in app.json/app.config.js

You can configure expo-screen-orientation using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.

Are you using this library in a bare React Native app?

Open the ios directory in Xcode with xed ios. If you don't have the directory, run npx expo prebuild -p ios to generate one.
Tick the Requires Full Screen checkbox in Xcode. It should be located under Project Target > General > Deployment Info.

Example app.json with config plugin

app.json

{
  "expo": {
    "ios": {
      "requireFullScreen": true
    },
    "plugins": [
      [
        "expo-screen-orientation",
        {
          "initialOrientation": "DEFAULT"
        }
      ]
    ]
  }
}

Configurable properties

Name	Default	Description
`initialOrientation`	`undefined`	Only for: iOS Sets the iOS initial screen orientation. Possible values: `DEFAULT`, `ALL`, `PORTRAIT`, `PORTRAIT_UP`, `PORTRAIT_DOWN`, `LANDSCAPE`, `LANDSCAPE_LEFT`, `LANDSCAPE_RIGHT`

API

import * as ScreenOrientation from 'expo-screen-orientation';

Methods

Android

iOS

Web

`ScreenOrientation.getOrientationAsync()`

Gets the current screen orientation.

Returns:

Promise<Orientation>

Returns a promise that fulfils with an Orientation value that reflects the current screen orientation.

Android

iOS

Web

`ScreenOrientation.getOrientationLockAsync()`

Gets the current screen orientation lock type.

Returns:

Promise<OrientationLock>

Returns a promise which fulfils with an OrientationLock value.

Android

iOS

Web

`ScreenOrientation.getPlatformOrientationLockAsync()`

Gets the platform specific screen orientation lock type.

Returns:

Promise<PlatformOrientationInfo>

Returns a promise which fulfils with a PlatformOrientationInfo value.

Android

iOS

Web

`ScreenOrientation.lockAsync(orientationLock)`

Parameter	Type	Description
orientationLock	`OrientationLock`	The orientation lock to apply. See the `OrientationLock` enum for possible values.

Lock the screen orientation to a particular OrientationLock.

Returns:

Promise<void>

Returns a promise with void value, which fulfils when the orientation is set.

Example

async function changeScreenOrientation() {
  await ScreenOrientation.lockAsync(ScreenOrientation.OrientationLock.LANDSCAPE_LEFT);
}

Android

iOS

Web

`ScreenOrientation.lockPlatformAsync(options)`

Parameter	Type	Description
options	`PlatformOrientationInfo`	The platform specific lock to apply. See the `PlatformOrientationInfo` object type for the different platform formats.

Returns:

Promise<void>

Returns a promise with void value, resolving when the orientation is set and rejecting if an invalid option or value is passed.

Android

iOS

Web

`ScreenOrientation.supportsOrientationLockAsync(orientationLock)`

Parameter	Type
orientationLock	`OrientationLock`

Returns whether the OrientationLock policy is supported on the device.

Returns:

Promise<boolean>

Returns a promise that resolves to a boolean value that reflects whether or not the orientationLock is supported.

Android

iOS

Web

`ScreenOrientation.unlockAsync()`

Sets the screen orientation back to the OrientationLock.DEFAULT policy.

Returns:

Promise<void>

Returns a promise with void value, which fulfils when the orientation is set.

Event Subscriptions

Android

iOS

Web

`ScreenOrientation.addOrientationChangeListener(listener)`

Parameter	Type	Description
listener	`OrientationChangeListener`	Each orientation update will pass an object with the new `OrientationChangeEvent` to the listener.

Invokes the listener function when the screen orientation changes from portrait to landscape or from landscape to portrait. For example, it won't be invoked when screen orientation change from portrait up to portrait down, but it will be called when there was a change from portrait up to landscape left.

Returns:

EventSubscription

Android

iOS

Web

`ScreenOrientation.removeOrientationChangeListener(subscription)`

Parameter	Type	Description
subscription	`EventSubscription`	A subscription object that manages the updates passed to a listener function on an orientation change.

Unsubscribes the listener associated with the Subscription object from all orientation change updates.

Returns:

void

Android

iOS

Web

`ScreenOrientation.removeOrientationChangeListeners()`

Removes all listeners subscribed to orientation change updates.

Returns:

void

Types

Android

iOS

Web

`OrientationChangeEvent`

Name	Type	Description
orientationInfo	`ScreenOrientationInfo`	The current `ScreenOrientationInfo` of the device.
orientationLock	`OrientationLock`	The current `OrientationLock` of the device.

Android

iOS

Web

`OrientationChangeListener()`

Parameter	Type
event	`OrientationChangeEvent`

Returns:

void

Android

iOS

Web

`PlatformOrientationInfo`

Name	Type	Description
screenOrientationArrayIOS (optional)	`Orientation[]`	Only for: iOS An array of orientations to allow on the iOS platform.
screenOrientationConstantAndroid (optional)	`number`	Only for: Android A constant to set using the Android native API. For example, in order to set the lock policy to unspecified, `-1` should be passed in.
screenOrientationLockWeb (optional)	`WebOrientationLock`	Only for: Web A web orientation lock to apply in the browser.

Android

iOS

Web

`ScreenOrientationInfo`

Name	Type	Description
horizontalSizeClass (optional)	`SizeClassIOS`	Only for: iOS The horizontal size class of the device.
orientation	`Orientation`	The current orientation of the device.
verticalSizeClass (optional)	`SizeClassIOS`	Only for: iOS The vertical size class of the device.

Android

iOS

Web

`Subscription`

A subscription object that allows to conveniently remove an event listener from the emitter.

Name	Type	Description
remove	`() => void`	Removes an event listener for which the subscription has been created. After calling this function, the listener will no longer receive any events from the emitter.

Enums

Android

iOS

Web

`Orientation`

Orientation Values

`UNKNOWN`

Orientation.UNKNOWN ＝ 0

An unknown screen orientation. For example, the device is flat, perhaps on a table.

`PORTRAIT_UP`

Orientation.PORTRAIT_UP ＝ 1

Right-side up portrait interface orientation.

`PORTRAIT_DOWN`

Orientation.PORTRAIT_DOWN ＝ 2

Upside down portrait interface orientation.

`LANDSCAPE_LEFT`

Orientation.LANDSCAPE_LEFT ＝ 3

Left landscape interface orientation.

`LANDSCAPE_RIGHT`

Orientation.LANDSCAPE_RIGHT ＝ 4

Right landscape interface orientation.

Android

iOS

Web

`OrientationLock`

An enum whose values can be passed to the lockAsync method.

Note: OrientationLock.ALL and OrientationLock.PORTRAIT are invalid on devices which don't support OrientationLock.PORTRAIT_DOWN.

OrientationLock Values

`DEFAULT`

OrientationLock.DEFAULT ＝ 0

The default orientation. On iOS, this will allow all orientations except Orientation.PORTRAIT_DOWN. On Android, this lets the system decide the best orientation.