Expo

Get Started
API Reference

ScreenOrientation

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
ScreenOrientation from expo allows changing supported screen orientations at runtime, and subscribing to orientation changes. This will take priority over the orientation key in app.json.
On both iOS and Android 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 support has limited support. For improved resize detection on mobile Safari, check out the docs on using Resize Observer in Expo web.

Platform Compatibility

Android DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb

Installation

Terminal
→ expo install expo-screen-orientation

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

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 the iOS, your iPad is always in the landscape mode unless you open two applications side by side. In order 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.

Managed workflow

Open your app.json and add the following inside of the "expo" field:
{
  "expo": {
    ...
    "ios": {
      ...
      "requireFullScreen": true,
    }
  }
}

Bare workflow

Tick the Requires Full Screen checkbox in Xcode. It should be located under Project Target > General > Deployment Info.

API

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

Methods

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.

Error codes

  • ERR_SCREEN_ORIENTATION_GET_ORIENTATION_LOCK - Android Only. An unknown error occurred when trying to get the system lock.
  • ERR_SCREEN_ORIENTATION_MISSING_ACTIVITY - Android Only. Could not get the current activity.

ScreenOrientation.getOrientationLockAsync()

Gets the current screen orientation lock type.

Returns

Returns a promise which fulfils with an OrientationLock value.

Error codes

  • ERR_SCREEN_ORIENTATION_MISSING_ACTIVITY - Android Only. Could not get the current activity.

ScreenOrientation.getPlatformOrientationLockAsync()

Gets the platform specific screen orientation lock type.

Returns

Returns a promise which fulfils with a PlatformOrientationInfo value.

Error codes

  • ERR_SCREEN_ORIENTATION_GET_PLATFORM_ORIENTATION_LOCK
  • ERR_SCREEN_ORIENTATION_MISSING_ACTIVITY - Android Only. Could not get the current activity.

ScreenOrientation.lockAsync(orientationLock)

Arguments

Lock the screen orientation to a particular OrientationLock.

Example

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

Returns

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

Error codes

  • ERR_SCREEN_ORIENTATION_INVALID_ORIENTATION_LOCK - An invalid OrientationLock was passed in.
  • ERR_SCREEN_ORIENTATION_UNSUPPORTED_ORIENTATION_LOCK - The platform does not support the orientation lock policy.
  • ERR_SCREEN_ORIENTATION_MISSING_ACTIVITY - Android Only. Could not get the current activity.

ScreenOrientation.lockPlatformAsync(options)

Arguments

Returns

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

Error codes

  • ERR_SCREEN_ORIENTATION_INVALID_ORIENTATION_LOCK - iOS Only. An invalid OrientationLock was passed in.
  • ERR_SCREEN_ORIENTATION_UNSUPPORTED_ORIENTATION_LOCK - The platform does not support the orientation lock policy.
  • ERR_SCREEN_ORIENTATION_MISSING_ACTIVITY - Android Only. Could not get the current activity.

ScreenOrientation.supportsOrientationLockAsync(orientationLock)

Arguments

Returns whether the OrientationLock policy is supported on the device.

Returns

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

ScreenOrientation.unlockAsync()

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

Returns

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

Error codes

  • ERR_SCREEN_ORIENTATION_MISSING_ACTIVITY - Android Only. Could not get the current activity.

Event Subscriptions

ScreenOrientation.addOrientationChangeListener(listener)

Arguments

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.

ScreenOrientation.removeOrientationChangeListener(subscription)

Arguments

  • subscription (Subscription) - 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.

ScreenOrientation.removeOrientationChangeListeners()

Removes all listeners subscribed to orientation change updates.

Types

OrientationChangeEvent

NameTypeDescription
orientationInfoScreenOrientationInfoThe current ScreenOrientationInfo of the device.
orientationLockOrientationLockThe current OrientationLock of the device.

PlatformOrientationInfo

NameTypeDescription
screenOrientationArrayIOS
(optional)		Orientation[]
iOS Only

An array of orientations to allow on the iOS platform.
screenOrientationConstantAndroid
(optional)		number
Android Only

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
Web Only

A web orientation lock to apply in the browser.

ScreenOrientationInfo

NameTypeDescription
horizontalSizeClass
(optional)		SizeClassIOS
iOS Only

The horizontal size class of the device.
orientationOrientationThe current orientation of the device.
verticalSizeClass
(optional)		SizeClassIOS
iOS Only

The vertical size class of the device.

Subscription

NameTypeDescription
remove() => voidA method to unsubscribe the listener.

Enums

Orientation

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

    Orientation.UNKNOWN ＝ 0

  • PORTRAIT_UP - Right-side up portrait interface orientation.

    Orientation.PORTRAIT_UP ＝ 1

  • PORTRAIT_DOWN - Upside down portrait interface orientation.

    Orientation.PORTRAIT_DOWN ＝ 2

  • LANDSCAPE_LEFT - Left landscape interface orientation.

    Orientation.LANDSCAPE_LEFT ＝ 3

  • LANDSCAPE_RIGHT - Right landscape interface orientation.

    Orientation.LANDSCAPE_RIGHT ＝ 4

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.
  • DEFAULT - The default orientation. On iOS, this will allow all orientations except Orientation.PORTRAIT_DOWN. On Android, this lets the system decide the best orientation.

    OrientationLock.DEFAULT ＝ 0

  • ALL - All four possible orientations

    OrientationLock.ALL ＝ 1

  • PORTRAIT - Any portrait orientation.

    OrientationLock.PORTRAIT ＝ 2

  • PORTRAIT_UP - Right-side up portrait only.

    OrientationLock.PORTRAIT_UP ＝ 3

  • PORTRAIT_DOWN - Upside down portrait only.

    OrientationLock.PORTRAIT_DOWN ＝ 4

  • LANDSCAPE - Any landscape orientation.

    OrientationLock.LANDSCAPE ＝ 5

  • LANDSCAPE_LEFT - Left landscape only.

    OrientationLock.LANDSCAPE_LEFT ＝ 6

  • LANDSCAPE_RIGHT - Right landscape only.

    OrientationLock.LANDSCAPE_RIGHT ＝ 7

  • OTHER - A platform specific orientation. This is not a valid policy that can be applied in lockAsync.

    OrientationLock.OTHER ＝ 8

  • UNKNOWN - An unknown screen orientation lock. This is not a valid policy that can be applied in lockAsync.

    OrientationLock.UNKNOWN ＝ 9

SizeClassIOS

Each iOS device has a default set of size classes that you can use as a guide when designing your interface.

  • REGULAR

    SizeClassIOS.REGULAR ＝ 0

  • COMPACT

    SizeClassIOS.COMPACT ＝ 1

  • UNKNOWN

    SizeClassIOS.UNKNOWN ＝ 2

WebOrientation

  • LANDSCAPE_PRIMARY

    WebOrientation.LANDSCAPE_PRIMARY ＝ "landscape-primary"

  • LANDSCAPE_SECONDARY

    WebOrientation.LANDSCAPE_SECONDARY ＝ "landscape-secondary"

  • PORTRAIT_PRIMARY

    WebOrientation.PORTRAIT_PRIMARY ＝ "portrait-primary"

  • PORTRAIT_SECONDARY

    WebOrientation.PORTRAIT_SECONDARY ＝ "portrait-secondary"

WebOrientationLock

An enum representing the lock policies that can be applied on the web platform, modelled after the W3C specification. These values can be applied through the lockPlatformAsync method.

  • ANY

    WebOrientationLock.ANY ＝ "any"

  • LANDSCAPE

    WebOrientationLock.LANDSCAPE ＝ "landscape"

  • LANDSCAPE_PRIMARY

    WebOrientationLock.LANDSCAPE_PRIMARY ＝ "landscape-primary"

  • LANDSCAPE_SECONDARY

    WebOrientationLock.LANDSCAPE_SECONDARY ＝ "landscape-secondary"

  • NATURAL

    WebOrientationLock.NATURAL ＝ "natural"

  • PORTRAIT

    WebOrientationLock.PORTRAIT ＝ "portrait"

  • PORTRAIT_PRIMARY

    WebOrientationLock.PORTRAIT_PRIMARY ＝ "portrait-primary"

  • PORTRAIT_SECONDARY

    WebOrientationLock.PORTRAIT_SECONDARY ＝ "portrait-secondary"

  • UNKNOWN

    WebOrientationLock.UNKNOWN ＝ "unknown"

Error Codes

CodeDescription
ERR_SCREEN_ORIENTATION_UNSUPPORTED_ORIENTATION_LOCKThe platform does not support the OrientationLock policy.
ERR_SCREEN_ORIENTATION_INVALID_ORIENTATION_LOCKAn invalid OrientationLock was passed in.
ERR_SCREEN_ORIENTATION_GET_ORIENTATION_LOCKAndroid Only. An unknown error occurred when trying to get the orientation lock.
ERR_SCREEN_ORIENTATION_GET_PLATFORM_ORIENTATION_LOCKAndroid Only. An unknown error occurred when trying to get the platform orientation lock.
ERR_SCREEN_ORIENTATION_MISSING_ACTIVITYAndroid Only. Could not get the current activity.