Screen Orientation API

With support for the W3C Screen Orientation API, you can detect the screen's current orientation, lock the orientation to a specific state, and be informed when it changes.

The Screen Orientation API enables you to prevent or override the browser from automatically reflowing your web app's content during changes to the orientation of your user's device. When using device orientation events, you can also use the Screen Orientation API to lock the display so that your user's device orientation and motion sensor data is accurate, and not invalidated or complicated by random screen orientation changes made by the user.

Note

This implementation for Screen Orientation API uses the ms prefix. Syntax seen in the latest Screen Orientation API spec(i.e. screen.orientation.lock instead of screen.lockOrientation) is not supported.

Orientation values

The Screen Orientation API uses the following concepts to describe the various orientation states across different devices. The example diagrams assume the following normal (default) orientation of the example devices:

Diagram of a mobile (portrait orientation) device and a tablet (landscape orientation) device.

Orientation value Description Example device orientation
portrait-primary The screen is in portrait mode, and the host device is right side up (if its normal orientation is in portrait mode), or the host device is rotated 90 degrees clockwise (if its normal orientation is in landscape mode). Illustration of the mobile device and tablet device orientation in "portrait-primary" mode
landscape-primary The screen is in landscape mode, and the host device is right side up (if its normal orientation is in landscape mode), or the host device is rotated 90 degrees counter-clockwise (if its normal orientation is in portrait mode). Illustration of the mobile device and tablet device orientation in "landscape-primary" mode
portrait-secondary The screen is in portrait mode, and the host device is upside down (if its normal orientation is in portrait mode), or the host device is rotated 90 degrees counter-clockwise (if its normal orientation is in landscape mode). Illustration of the mobile device and tablet device orientation in "portrait-secondary" mode
landscape-secondary The screen is in landscape mode, and the host device is upside down (if its normal orientation is in landscape mode), or the host device is rotated 90 degrees clockwise (if its normal orientation is in portrait mode). Illustration of the mobile device and tablet device orientation in "landscape-secondary" mode

Detecting changes and locking orientation

To monitor when the orientation of your user's screen changes, listen for the the MSOrientationChange event of the screen object, which dispatches a simple Event object. From this, you can determine the current screen orientation from the msOrientation property of the screen object:

function orientationChangeHandler(evt) {
  var orientation = evt.target.msOrientation;
  // Respond to the screen orientation change
}

To lock the display to a specific orientation, call the msLockOrientation method and pass it one or more of the values described in the Orientation values section above:

screen.msLockOrientation("portrait-primary", "portrait-secondary"); 

Alternatively, you can pass it one of the following "shorthand" values:

Value Description
portrait Value that represents both portrait-primary and portrait-secondary cases.
landscape Value that represents both landscape-primary and landscape-secondary cases.

Locking the screen orientation is only possible when Microsoft Edge is in full screen mode (by the user pressing F11, or via the Fullscreen API). If the lock is done on only one orientation, the screen stays on the given orientation and never changes until the screen orientation is unlocked. Otherwise, the screen orientation can change between any of the specified orientations it is locked to, as the user rotates the host device.

To unlock, call the screen.msUnlockOrientation method.

API reference

msOrientation

MSOrientationChange

msLockOrientation

msUnlockOrientation

Specification

Screen Orientation API