The Screen Orientation specification standardizes the types and angles for a device's screen orientation, and provides a means for locking and unlocking it. The API, defined by this specification, exposes the current type and angle of the device's screen orientation, and dispatches events when it changes. This enables web applications to programmatically adapt the user experience for multiple screen orientations, working alongside CSS. This API is particularly useful for applications such as computer games, where users physically rotate the device, but the screen orientation itself should not change. The API restricts locking the screen orientation only if certain [=pre-lock conditions=] are met.

This document is a work in progress.

Concepts

To lock the screen orientation to an {{OrientationLockType}} |orientation| means that the screen can only be rotated by the user to a specific [=screen orientation=] - possibly at the exclusion of other orientations. The possible orientations to which the screen can be rotated is determined by the user agent, a user preference, the operating system's conventions, or the screen itself. For example, locking the orientation to [=landscape=] means that the screen can be rotated by the user to [=landscape-primary=] and maybe [=landscape-secondary=] if the system allows it, but won't change the orientation to [=portrait-secondary=] orientation.

To unlock the screen orientation the end user is unrestricted to rotate the screen to any [=screen orientation=] that the system allows.

Extensions to the `Document` interface

Extensions to the `Screen` interface

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

The {{Window}} object has an associated `ScreenOrientation`, which is a {{Screen}}'s {{Screen/orientation}} object (i.e., the {{ScreenOrientation}} instance at `window.screen.orientation`).

ScreenOrientation interface

        [Exposed=Window]
        interface ScreenOrientation : EventTarget {
          Promise<undefined> lock(OrientationLockType orientation);
          undefined unlock();
          readonly attribute OrientationType type;
          readonly attribute unsigned short angle;
          attribute EventHandler onchange;
        };
      

The {{onchange}} attribute is an [=event handler IDL attribute=] for the {{onchange}} [=event handler=], whose [=event handler event type=] is change.

OrientationLockType enum

        enum OrientationLockType {
          "any",
          "natural",
          "landscape",
          "portrait",
          "portrait-primary",
          "portrait-secondary",
          "landscape-primary",
          "landscape-secondary"
        };
      

The {{OrientationLockType}} enum represents the screen orientations to which a screen can be potentially [=locked=].

• "any" represents [=any=].
• "natural" represents [=natural=].
• "landscape" represents [=landscape=].
• "portrait" represents [=portrait=].
• "portrait-primary" represents [=portrait-primary=].
• "portrait-secondary" represents [=portrait-secondary=].
• "landscape-primary" represents [=landscape-primary=].
• "landscape-secondary" represents [=landscape-secondary=].

OrientationType enum

        enum OrientationType {
          "portrait-primary",
          "portrait-secondary",
          "landscape-primary",
          "landscape-secondary"
        };
      

The {{OrientationType}} enum values are used to represent the screen's [=Screen/current orientation type=].

• "portrait-primary" represents [=portrait-primary=].
• "portrait-secondary" represents [=portrait-secondary=].
• "landscape-primary" represents [=landscape-primary=].
• "landscape-secondary" represents [=landscape-secondary=].

Algorithms

Applying an orientation lock

When steps require to apply orientation lock of {{OrientationLockType?}} |orientation| to {{Document}} |document|, the [=user agent=] MUST perform the following steps:

1. If |document| stops being [=Document/fully active=] while [=in parallel=], and {{Document/[[orientationPendingPromise]]}} is not `null`, [=reject and nullify the current lock promise=] of |document| with an {{"AbortError"}}.
2. Let |topDocument| be |document|'s [=top-level traversable=]'s [=navigable/active document=].
3. Let |descendantDocs| be an [=ordered set=] consisting of |topDocument|'s [=Document/descendant navigables=]'s [=navigable/active documents=], if any, in tree order.
4. [=Set/For each=] |doc:Document| in |descendantDocs|:
   1. If |doc| is |document|, continue.
   2. If |doc|'s {{Document/[[orientationPendingPromise]]}} is `null`, continue.
   3. [=Reject and nullify the current lock promise=] of |doc| with an {{"AbortError"}}.
5. Run the following sub-steps [=in parallel=]:
   1. If |document| has stopped being [=Document/fully active=], and if the |document|'s {{Document/[[orientationPendingPromise]]}} is not `null`, [=reject and nullify the current lock promise=] of |document| with an {{"AbortError"}} and abort these steps.
   2. If |orientation| is `null`, [=unlock the screen orientation=].
   3. Otherwise, attempt to [=lock the screen orientation=] to |orientation|. Depending on platform conventions, change how the viewport is drawn to match |orientation|.
   4. If the attempt fails due to previously-established user preference, or platform limitation, or any other reason:
      1. Set the screen's [=Screen/active orientation lock=] to `null`.
      2. [=Queue a task=] on the [=DOM manipulation task source=] with |document|'s [=relevant global object=] to:
         1. If the |document|'s {{Document/[[orientationPendingPromise]]}} is not `null`, [=reject and nullify the current lock promise=] of |document| with a {{"NotSupportedError"}}.
         2. Abort these steps.

      This can happen if the user has set a preference that prevents web applications from changing the screen orientation, or if the underlying platform, rather than the user agent, does not allow locking the screen orientation to the given |orientation|. Note that differences in user preferences or platform capabilities could potentially be used for fingerprinting, as they may create detectable patterns in lock failure behavior.

   5. Set the screen's [=Screen/active orientation lock=] to |orientation| and update the [=Screen/current orientation type=] and [=Screen/current orientation angle=] to reflect any changes to the [=screen orientation=].
6. [=Queue a global task=] on the [=DOM manipulation task source=] with |document|'s [=relevant global object=] to:
   1. Let |promise:Promise?| be |document|'s {{Document/[[orientationPendingPromise]]}}.
   2. Set |document|'s {{Document/[[orientationPendingPromise]]}} to `null`.
   3. Run the [=screen orientation change steps=] with |topDocument|.
   4. If |promise| is not `null`, [=resolve=] |promise| with `undefined`.

Screen orientation change

When a user-agent determines that the screen's orientation has changed for a [=top-level traversable=], or the user moves the [=top-level browsing context=] to a different screen, then run the [=screen orientation change steps=] with the [=top-level traversable=]'s [=navigable/active document=].

The screen orientation change steps for {{Document}} |document:Document| are as follows:

1. If |document| is not a [=Document/fully active descendant of a top-level traversable with user attention=], abort these steps.
2. Let |type| and |angle| be the screen's [=Screen/current orientation type=] and [=Screen/current orientation angle=].
3. Let |screenOrientation| be |document|'s [=relevant global object=]'s [=associated `ScreenOrientation`=].
4. If |type| is equal to |screenOrientation|'s {{ScreenOrientation/[[type]]}} and |angle| is equal to |screenOrientation|'s {{ScreenOrientation/[[angle]]}}, abort these steps.
5. [=Queue a global task=] on the [=user interaction task source=] with |document|'s [=relevant global object=] to perform the following steps:
   1. Set |screenOrientation|'s {{ScreenOrientation/[[angle]]}} to |angle|.
   2. Set |screenOrientation|'s {{ScreenOrientation/[[type]]}} to |type|.
   3. [=Fire an event=] named "change" at |screenOrientation|.
6. Let |descendantDocs| be an [=ordered set=] consisting of |document|'s [=Document/descendant navigables=]'s [=navigable/active documents=], if any, in tree order.
7. [=Set/For each=] |doc:Document| in |descendantDocs|, run the [=screen orientation change steps=] with |doc|.

Handling page visibility changes

[[HTML]]'s "update the visibility state" algorithm runs the [=screen orientation change steps=].

Handling unloading documents

Whenever the [=unloading document cleanup steps=] run with a |document|, the user agent MUST run the following steps:

1. If |document| is not a [=top-level traversable=]'s [=navigable/active document=], abort these steps.
2. Run the [=fully unlock the screen orientation steps=] with |document|.

Fully unlocking the orientation

The fully unlock the screen orientation steps for {{Document}} |document:Document| are as follows:

1. If |document|'s {{Document/[[orientationPendingPromise]]}} is not `null`, [=reject and nullify the current lock promise=] of |document| with an {{"AbortError"}}.
2. Let |topDocument| be |document|'s [=top-level traversable=]'s [=navigable/active document=].
3. [=Apply orientation lock=] `null` to |topDocument|.

Interaction with Fullscreen API

A user agent MUST restrict the use of {{ScreenOrientation/lock()}} to simple fullscreen documents as a [=pre-lock condition=]. This requirement prevents fingerprinting through differences in user agent behavior regarding orientation locking permissions. [[fullscreen]]

When a [=document=] exits fullscreen, it also runs the [=fully unlock the screen orientation steps=]. [[fullscreen]]

Interaction with Web Application Manifest

The [[[appmanifest]]] specification allows web applications to set the [=default screen orientation=] via the the [=manifest/orientation=] member.

A user agent SHOULD require [=installed web applications=] to be presented in the "fullscreen" [=display mode=] as a [=pre-lock condition=].

Accessibility considerations

As users can have their devices mounted in a fixed orientation (e.g. on the arm of a wheelchair), developers that expect users to rotate their device when [=locking the screen orientation=] need to be aware of the [[[WCAG21]]]'s Orientation Success Criterion. The criterion makes it essential that content and functionality is available regardless of the [=screen orientation=]. When a particular orientation is essential, web applications must advise the user of the orientation requirements.

Privacy and Security Considerations

A screen's [=Screen/current orientation type|type=] and [=Screen/current orientation angle|angle=] are a potential fingerprinting vectors. The following mitigations help protect a user's privacy by not revealing how a device is being held, and also prevent the [=secondary=] orientation type and associated angles from being used for fingerprinting purposes.

Event Delivery Restrictions

To protect user privacy, orientation change events are subject to several delivery restrictions:

• Events only fire on a [=document=] that is a [=Document/fully active descendant of a top-level traversable with user attention=].
• Additional [=Document/visibility state=] checks provide defense-in-depth against hidden documents.
• Events originate from the [=navigable/active document=] of a [=top-level traversable=] and propagate to descendant documents.

The requirement for [=documents=] to be [=Document/fully active descendant of a top-level traversable with user attention=] ensures that orientation events are only delivered to documents in windows that are both visible at the system level and have the user's attention (either through focus or the ability to receive keyboard input). The additional visibility state check provides defense in depth. These restrictions prevent background tabs, hidden windows, and minimized applications from collecting orientation data for fingerprinting purposes.

Anti-fingerprinting Mitigations

To resist fingerprinting, user agents SHOULD implement the following protections, particularly in privacy-conscious contexts such as private browsing modes:

1. For the life of a [=top-level traversable=], behave as if the screen's [=natural=] orientation is {{ScreenOrientation/[[initialType]]}}.
2. Restrict the possible return values of the {{ScreenOrientation/type}} getter to {{OrientationType/"portrait-primary"}} or {{OrientationType/"landscape-primary"}}. The screen aspect ratio determines which is returned.
3. If the [=Screen/current orientation type=] matches {{ScreenOrientation/[[initialType]]}}, return `0` for the {{ScreenOrientation/angle}} getter. Otherwise, return `90`.
4. If the screen orientation changes, only fire the change event when the [=Screen/current orientation type=] changes from [=portrait=] to [=landscape=], or vice versa.