Expo

Documentation

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
This API allows changing supported screen orientations at runtime. 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.

Installation

This API is pre-installed in managed apps. It is not yet available for bare React Native apps.

API

import { ScreenOrientation } from 'expo';

Methods

Enum Types

Object Types

Function Types

Errors

Methods

ScreenOrientation.allowAsync(orientationLock)

Deprecated in favor of ScreenOrientation.lockAsync. Allow a screen orientation.

Arguments

  • orientation (OrientationLock) -- The orientation lock to apply. See the OrientationLock enum for possible values.

Returns

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

Example

function changeScreenOrientation() {
  await ScreenOrientation.allowAsync(ScreenOrientation.Orientation.LANDSCAPE);
}

ScreenOrientation.lockAsync(orientationLock)

Lock the screen orientation to a particular OrientationLock.

Arguments

  • orientationLock (OrientationLock) -- The orientation lock to apply. See the OrientationLock enum for possible values.

Returns

Returns a promise with void value, resolving 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.

Example

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

ScreenOrientation.lockPlatformAsync(platformInfo)

Arguments

  • platformInfo (PlatformOrientationInfo) -- The platform specific lock to apply. See the PlatformOrientationInfo object type for the different platform formats.

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 - an invalid OrientationLock was passed in.
  • ERR_SCREEN_ORIENTATION_UNSUPPORTED_ORIENTATION_LOCK - the platform does not support the orientation lock policy.

ScreenOrientation.unlockAsync()

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

Returns

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

ScreenOrientation.getOrientationAsync()

Gets the current screen orientation.

Returns

Returns a promise that resolves to an OrientationInfo object value that reflects the current screen orientation.

ScreenOrientation.getOrientationLockAsync()

Gets the current screen orientation lock type.

Returns

Returns a promise with an OrientationLock value.

ScreenOrientation.getPlatformOrientationLockAsync()

Gets the platform specific screen orientation lock type.

Returns

Returns a promise with a PlatformOrientationInfo value.

ScreenOrientation.supportsOrientationLockAsync(orientationLock)

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.addOrientationChangeListener(listener)

Invokes the listener function when the screen orientation changes.

Arguments

  • listener (OrientationChangeListener)

Returns

Returns an Subscription object that can later be used to unsuscribe updates to the listener.

ScreenOrientation.removeOrientationChangeListeners()

Removes all listeners subscribed to orientation change updates.

ScreenOrientation.removeOrientationChangeListener(subscription)

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

Arguments

  • subscription (Subscription)
    • A subscription object that manages the updates passed to a listener function on an orientation change.

Enum types

ScreenOrientation.Orientation

  • Orientation.UNKNOWN - An unknown screen orientation. For example, the device is flat, perhaps on a table.
  • Orientation.PORTRAIT - Portrait interface orientation (right side up or upside down).
  • Orientation.PORTRAIT_UP - Right-side up portrait interface orientation.
  • Orientation.PORTRAIT_DOWN - Upside down portrait interface orientation.
  • Orientation.LANDSCAPE - Landscape interface orientation (right or left).
  • Orientation.LANDSCAPE_LEFT - Left landscape interface orientation.
  • Orientation.LANDSCAPE_RIGHT - Right landscape interface orientation.

ScreenOrientation.OrientationLock

An enum whose values can be passed to the lockAsync method.
  • OrientationLock.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.ALL -- All four possible orientations
  • OrientationLock.PORTRAIT -- Any portrait orientation.
  • OrientationLock.PORTRAIT_UP -- Right-side up portrait only.
  • OrientationLock.PORTRAIT_DOWN -- Upside down portrait only.
  • OrientationLock.LANDSCAPE -- Any landscape orientation.
  • OrientationLock.LANDSCAPE_LEFT -- Left landscape only.
  • OrientationLock.LANDSCAPE_RIGHT -- Right landscape only.
  • OrientationLock.OTHER -- A platform specific orientation. This is not a valid policy that can be applied in lockAsync.
  • OrientationLock.UNKNOWN -- An unknown screen orientation lock. This is not a valid policy that can be applied in lockAsync.

ScreenOrientation.SizeClassIOS

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

ScreenOrientation.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.
  • PORTRAIT_PRIMARY
  • PORTRAIT_SECONDARY
  • PORTRAIT
  • LANDSCAPE_PRIMARY
  • LANDSCAPE_SECONDARY
  • LANDSCAPE
  • ANY
  • UNKNOWN

Object Types

ScreenOrientation.PlatformOrientationInfo

- screenOrientationConstantAndroid (_integer_): A constant to set using the Android native [API](https://developer.android.com/reference/android/R.attr.html#screenOrientation). For example, in order to set the lock policy to [unspecified](https://developer.android.com/reference/android/content/pm/ActivityInfo.html#SCREEN_ORIENTATION_UNSPECIFIED), -1 should be passed in. (Android only)
- screenOrientationArrayIOS (Array[Orientation]): An array of orientations to allow on the iOS platform (iOS only)
- screenOrientationLockWebOrientation (_WebOrientationLock_): A web orientation lock to apply in the browser (web only)

ScreenOrientation.OrientationInfo

- orientation (_Orientation_): The current orientation of the device
- verticalSizeClass (_SizeClassIOS_): The [vertical size class](https://developer.apple.com/library/archive/featuredarticles/ViewControllerPGforiPhoneOS/TheAdaptiveModel.html) of the device (iOS only)
- horizontalSizeClass (_SizeClassIOS_): The [horizontal size class](https://developer.apple.com/library/archive/featuredarticles/ViewControllerPGforiPhoneOS/TheAdaptiveModel.html) of the device (iOS only)

ScreenOrientation.OrientationChangeEvent

- orientationLock (_OrientationLock_): The current OrientationLock of the device.
- orientationInfo (_OrientationInfo_): The current OrientationInfo of the device.

Subscription

A subscription object.

Function Types

ScreenOrientation.OrientationChangeListener

Args

- event (_OrientationChangeEvent_): An update with the most recent OrientationChangeEvent.

Returns

void

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.