What is the Screen Orientation API and How to Use It

The Screen Orientation API provides web applications with the ability to read the device's current screen orientation, rotation angle, lock the orientation, and receive orientation change events, which can improve user experience for video playback and games. The specification is currently a working draft, last updated on January 29.

Property Structure

partial interface Screen {
  [SameObject] readonly attribute ScreenOrientation orientation;
};

interface ScreenOrientation : EventTarget {
  Promise
lock(OrientationLockType orientation);
  void unlock();
  readonly attribute OrientationType type;
  readonly attribute unsigned short angle;
  attribute EventHandler onchange;
};

To read the orientation, use the type property for a descriptive direction and the angle property for the rotation in degrees.

angle returns the rotation angle measured counter‑clockwise from the device's natural position (e.g., rotating a phone 90° counter‑clockwise yields an angle of 90).

type can be one of four values:

portrait-primary : upright portrait, 0°

portrait-secondary : upside‑down portrait, 180°

landscape-primary : landscape, 90°

landscape-secondary : landscape, 180°

Locking the Screen Orientation

Locking requires the page to be in fullscreen mode. Use the lock method with a direction string, which returns a Promise.

String

Meaning

portrait-primary

Portrait primary

portrait-secondary

Portrait secondary

landscape-primary

Landscape primary

landscape-secondary

Landscape secondary

portrait

Any portrait orientation

landscape

Any landscape orientation

natural

Device's natural orientation

any

Lock to the current orientation

Example of locking to portrait:

async function lockPortrait() {
  // Enter fullscreen first
  await document.documentElement.requestFullscreen();
  // Lock to portrait orientation
  await screen.orientation.lock('portrait')
    .catch(e => alert(e.message));
}

Unlocking

function unlock() {
  screen.orientation.unlock();
}

Orientation Change Events

Assign a handler to onchange or use addEventListener('change', …) to react to orientation changes.

function rotationChange() {
  console.log('rotation changed to:', screen.orientation.type);
}
screen.orientation.addEventListener('change', rotationChange);

In summary, using the Screen Orientation API is straightforward; it works well on mobile Chrome and Firefox, allowing developers to lock orientation and improve the browsing experience. A simple demo is available at https://codepen.io/NimitzDEV/pen/LaEapX.

Reference: W3C Screen Orientation API Draft