HomeGuidesReferenceLearn

Reference version

ArchiveExpo SnackDiscord and ForumsNewsletter

Expo ScreenOrientation iconExpo 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.

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'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 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?
  1. Open the ios/ directory in Xcode with xed ios. If you don't have an ios/ directory, run npx expo prebuild -p ios to generate one.
  2. 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

NameDefaultDescription
initialOrientationundefinedOnly 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

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.

ScreenOrientation.getOrientationLockAsync()

Gets the current screen orientation lock type.

Returns

  • Promise<OrientationLock>

Returns a promise which fulfils with an OrientationLock value.

ScreenOrientation.getPlatformOrientationLockAsync()

Gets the platform specific screen orientation lock type.

Returns

  • Promise<PlatformOrientationInfo>

Returns a promise which fulfils with a PlatformOrientationInfo value.

ScreenOrientation.lockAsync(orientationLock)

NameTypeDescription
orientationLockOrientationLock

The orientation lock to apply. See the OrientationLock enum for possible values.


Lock the screen orientation to a particular OrientationLock.

Example

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

Returns

  • Promise<void>

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

ScreenOrientation.lockPlatformAsync(options)

NameTypeDescription
optionsPlatformOrientationInfo

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.

ScreenOrientation.supportsOrientationLockAsync(orientationLock)

NameTypeDescription
orientationLockOrientationLock-

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.

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

ScreenOrientation.addOrientationChangeListener(listener)

NameTypeDescription
listenerOrientationChangeListener

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

  • Subscription

ScreenOrientation.removeOrientationChangeListener(subscription)

NameTypeDescription
subscriptionSubscription

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

ScreenOrientation.removeOrientationChangeListeners()

Removes all listeners subscribed to orientation change updates.

Returns

  • void

Types

OrientationChangeEvent

NameTypeDescription
orientationInfoScreenOrientationInfo

The current ScreenOrientationInfo of the device.

orientationLockOrientationLock

The current OrientationLock of the device.

OrientationChangeListener()

NameTypeDescription
eventOrientationChangeEvent-

PlatformOrientationInfo

NameTypeDescription
screenOrientationArrayIOS
(optional)
Orientation[]Only for:
iOS

An array of orientations to allow on the iOS platform.

screenOrientationConstantAndroid
(optional)
numberOnly 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)
WebOrientationLockOnly for:
Web

A web orientation lock to apply in the browser.

ScreenOrientationInfo

NameTypeDescription
horizontalSizeClass
(optional)
SizeClassIOSOnly for:
iOS

The horizontal size class of the device.

orientationOrientation

The current orientation of the device.

verticalSizeClass
(optional)
SizeClassIOSOnly for:
iOS

The vertical size class of the device.

Subscription

NameTypeDescription
remove() => void

A method to unsubscribe the listener.

Enums

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.

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.

ALL

OrientationLock.ALL = 1

All four possible orientations

PORTRAIT

OrientationLock.PORTRAIT = 2

Any portrait orientation.

PORTRAIT_UP

OrientationLock.PORTRAIT_UP = 3

Right-side up portrait only.

PORTRAIT_DOWN

OrientationLock.PORTRAIT_DOWN = 4

Upside down portrait only.

LANDSCAPE

OrientationLock.LANDSCAPE = 5

Any landscape orientation.

LANDSCAPE_LEFT

OrientationLock.LANDSCAPE_LEFT = 6

Left landscape only.

LANDSCAPE_RIGHT

OrientationLock.LANDSCAPE_RIGHT = 7

Right landscape only.

OTHER

OrientationLock.OTHER = 8

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

UNKNOWN

OrientationLock.UNKNOWN = 9

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

SizeClassIOS

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

SizeClassIOS Values

REGULAR

SizeClassIOS.REGULAR = 0

COMPACT

SizeClassIOS.COMPACT = 1

UNKNOWN

SizeClassIOS.UNKNOWN = 2

WebOrientation

WebOrientation Values

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.

WebOrientationLock Values

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"