Abstract

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.

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C standards and drafts index.

This document is a work in progress.

This document was published by the Web Applications Working Group as a Working Draft using the Recommendation track.

Publication as a Working Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to cite this document as other than a work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent that the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 18 August 2025 W3C Process Document.

This section is non-normative.

In this example, selecting the "Lock" button requests to go into fullscreen and then locks the screen to the opposite orientation. Selecting the "Unlock" button unlocks the screen.

Example 1

: Locking to a specific orientation and unlocking

<script>
function updateLockButton() {
  const lockButton = document.getElementById("button");
  const newOrientation = getOppositeOrientation();
  lockButton.textContent = `Lock to ${newOrientation}`;
}
function getOppositeOrientation() {
  return screen
    .orientation
    .type
    .startsWith("portrait") ? "landscape" : "portrait";
}
async function rotate(lockButton) {
  if (!document.fullscreenElement) {
    await document.documentElement.requestFullscreen();
  }
  const newOrientation = getOppositeOrientation();
  await screen.orientation.lock(newOrientation);
  updateLockButton(lockButton);
}
screen.orientation.addEventListener("change", updateLockButton);
window.addEventListener("load", updateLockButton);
</script>
<button onclick="rotate(this)" id="button">
  Lock to...
</button>
<button onclick="screen.orientation.unlock()">
  Unlock
</button>

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.

A screen can be in, or locked to, one of the following screen orientations :

Any: The screen can be rotated by the user to any orientation allowed by the device's operating system or by the end-user.
Default (unlocked): The device's default behavior for when the screen is unlocked (i.e., the active orientation lock is null). This orientation is determined by the device's operating system, or the user agent, or controlled by the end-user, or possibly set by an installed web application. For example, when the screen orientation is unlocked and the user rotates the device, some devices will limit orientation changes to portrait-primary, landscape-primary, and landscape-secondary, but not to portrait-secondary.
Landscape: The screen's aspect ratio has a width greater than the height.
Natural: The reference orientation for the device's display, from which orientation angles are measured, as determined by the user agent, the user, the operating system, or the screen itself. For example, a computer monitor's reference orientation is typically landscape-primary, while the reference orientation for a mobile phone is typically portrait-primary.
Note
How a user agent determines the natural orientation is implementation-defined and varies by platform. Some user agents use a fixed orientation per device class (for example, portrait-primary for handsets and landscape-primary for tablets, desktops, and TVs), while others derive it from the screen's physical dimensions and its default rotation. For devices without an obvious upright, such as square or foldable screens, the natural orientation can therefore differ between user agents.
Portrait: The screen's aspect ratio has a height greater than the width.
Primary: The device's screen natural orientation for either portrait or landscape.
Secondary: The opposite of the device's screen primary orientation for portrait or landscape.

The screen of the output device has the following associated concepts:

Active orientation lock: The screen orientation, represented as a OrientationLockType, to which the screen is locked, or null when unlocked.
Current orientation angle: The angle in degrees that the screen is rotated counter-clockwise from its natural orientation as derived from the screen orientation values lists.
Current orientation type: The screen orientation of the screen, represented as a OrientationType.

The screen orientation values lists below standardize the angles associated with each screen orientation type for screens with different natural orientations:

For screens with a natural portrait orientation:

For screens with a natural landscape orientation:

The Document interface is extended with the following internal slots:

Internal Slot	Description
[[orientationPendingPromise]]	Either `null` or a `Promise`. When assigned a `Promise`, that promise represents a request to lock the screen orientation.

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

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

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

Internal Slot	Description
[[angle]]	Represents the screen's last known current orientation angle in degrees as an `unsigned short` as derived from the screen orientation values lists.
[[initialType]]	Represents the screen's current orientation type when the browsing context was created.
[[type]]	Represents the screen's last known current orientation type as an `OrientationType` enum value.

pre-lock conditions are optional requirements that a user agent MAY impose before allowing screen orientation locking. Common pre-lock conditions include requiring the document to be in fullscreen mode or being part of an installed web application. See 10. Interaction with Web Application Manifest and 9. Interaction with Fullscreen API for specific examples.

When the lock() method is invoked with OrientationLockType orientation, the user agent MUST run the following steps.

Let document be this's relevant global object's associated Document.
Run the common safety checks with document. If an exception is thrown, return a promise rejected with that exception and abort these steps.
If the user agent does not support locking the screen orientation to orientation, return a promise rejected with a "NotSupportedError" DOMException and abort these steps.
If the user agent requires document and its associated browsing context to meet pre-lock conditions in order to lock the screen orientation, and those conditions are not met, return a promise rejected with a "NotAllowedError" DOMException and abort these steps.
If document's [[orientationPendingPromise]] is not null, reject and nullify the current lock promise of document with an "AbortError".
Set document's [[orientationPendingPromise]] to a new promise.
Apply orientation lock orientation to document.
Return document's [[orientationPendingPromise]].

When the unlock() method is invoked, the user agent MUST run the following steps:

Let document be this's relevant global object's associated Document.
Run the common safety checks with document. If an exception is thrown, re-throw that exception and abort these steps.
If screen's active orientation lock is null, return undefined.
If document's [[orientationPendingPromise]] is not null, reject and nullify the current lock promise of document with an "AbortError".
Apply orientation lock null to document.

Note: Why does unlock() not return a promise?

unlock() does not return a promise because it is equivalent to locking to the default screen orientation which might or might not be known by the user agent. Hence, the user agent can not predict what the new orientation is going to be and even if it is going to change at all.

The common safety checks for a Document document are the following steps:

If document is not a fully active descendant of a top-level traversable with user attention, throw an "InvalidStateError" DOMException.
If document has the sandboxed orientation lock browsing context flag set, throw "SecurityError" DOMException.
If document's visibility state is "hidden", throw "SecurityError" DOMException.

When getting, the type attribute returns this's [[type]].

When getting, the angle attribute returns this's [[angle]].

Note: What does the value given for angle represent?

The onchange attribute is an event handler IDL attribute for the onchange event handler, whose event handler event type is change .

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.

Note: Orientation support

" 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.

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

The OrientationType enum values are used to represent the screen's current orientation type.

" portrait-primary " represents portrait-primary.
" portrait-secondary " represents portrait-secondary.
" landscape-primary " represents landscape-primary.
" landscape-secondary " represents landscape-secondary.

When a browsing context context is created, the user agent MUST:

Let screenOrientation be context's associated ScreenOrientation.
Initialize screenOrientation's [[initialType]] internal slot to the screen's current orientation type.
Initialize screenOrientation's [[type]] internal slot to the screen's current orientation type.
Initialize screenOrientation's [[angle]] internal slot to the screen's current orientation angle.

When steps require to reject and nullify the current lock promise of Document document with a DOMString exceptionName, the user agent MUST:

Assert: [[orientationPendingPromise]] is not null.
Let promise be document's [[orientationPendingPromise]].
Queue a global task on the DOM manipulation task source with document's relevant global object to reject promise with a new exceptionName DOMException.
Set document's [[orientationPendingPromise]] to null.

When steps require to apply orientation lock of OrientationLockType? orientation to Document document, the user agent MUST perform the following steps:

If document stops being fully active while in parallel, and [[orientationPendingPromise]] is not null, reject and nullify the current lock promise of document with an "AbortError".
Let topDocument be document's top-level traversable's active document.
Let descendantDocs be an ordered set consisting of topDocument's descendant navigables's active documents, if any, in tree order.
For each doc in descendantDocs:
1. If doc is document, continue.
2. If doc's [[orientationPendingPromise]] is null, continue.
3. Reject and nullify the current lock promise of doc with an "AbortError".
Run the following sub-steps in parallel:
1. If document has stopped being fully active, and if the document's [[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 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 [[orientationPendingPromise]] is not null, reject and nullify the current lock promise of document with a "NotSupportedError".
    2. Abort these steps.
  Note
  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 active orientation lock to orientation and update the current orientation type and current orientation angle to reflect any changes to the screen orientation.
Queue a global task on the DOM manipulation task source with document's relevant global object to:
1. Let promise be document's [[orientationPendingPromise]].
  Note
2. Set document's [[orientationPendingPromise]] to null.
3. Run the screen orientation change steps with topDocument.
4. If promise is not null, resolve promise with undefined.

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 active document.

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

If document is not a fully active descendant of a top-level traversable with user attention, abort these steps.
Let type and angle be the screen's current orientation type and current orientation angle.
Let screenOrientation be document's relevant global object's associated ScreenOrientation.
If type is equal to screenOrientation's [[type]] and angle is equal to screenOrientation's [[angle]], abort these steps.
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 [[angle]] to angle.
2. Set screenOrientation's [[type]] to type.
3. Fire an event named "change" at screenOrientation.
Let descendantDocs be an ordered set consisting of document's descendant navigables's active documents, if any, in tree order.
For each doc in descendantDocs, run the screen orientation change steps with doc.

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

Note

Whenever the unloading document cleanup steps run with a document, the user agent MUST run the following steps:

If document is not a top-level traversable's active document, abort these steps.
Run the fully unlock the screen orientation steps with document.

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

If document's [[orientationPendingPromise]] is not null, reject and nullify the current lock promise of document with an "AbortError".
Let topDocument be document's top-level traversable's active document.
Apply orientation lock null to topDocument.

A user agent MUST restrict the use of 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]

The Web Application Manifest specification allows web applications to set the default screen orientation via the the orientation member.

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

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 Web Content Accessibility Guidelines (WCAG) 2.1'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.

A screen's type and 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.

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

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

The requirement for documents to be 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.

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

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

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

partial interface Screen {
  [SameObject] readonly attribute ScreenOrientation  orientation ;
};
[Exposed=Window]
interface ScreenOrientation : EventTarget {
  Promise<undefined>  lock (OrientationLockType orientation);
  undefined  unlock ();
  readonly attribute OrientationType  type ;
  readonly attribute unsigned short  angle ;
  attribute EventHandler  onchange ;
};
enum OrientationLockType {
  "any",
  "natural",
  "landscape",
  "portrait",
  "portrait-primary",
  "portrait-secondary",
  "landscape-primary",
  "landscape-secondary"
};
enum OrientationType {
  "portrait-primary",
  "portrait-secondary",
  "landscape-primary",
  "landscape-secondary"
};

Active orientation lock §2.2
angle attribute for ScreenOrientation §5.
[[angle]] internal slot for ScreenOrientation §5.1
"any" enum value for OrientationLockType §6.
Any §2.1
apply orientation lock §8.3
associated ScreenOrientation §4.
change §5.
common safety checks §5.4
Current orientation angle §2.2
Current orientation type §2.2
Default §2.1
fully unlock the screen orientation steps §8.7
[[initialType]] internal slot for ScreenOrientation §5.1
"landscape" enum value for OrientationLockType §6.
Landscape §2.1
landscape-primary
- enum value for OrientationLockType §6.
- enum value for OrientationType §7.
landscape-secondary
- enum value for OrientationLockType §6.
- enum value for OrientationType §7.
lock method for ScreenOrientation §5.
lock the screen orientation §2.
"natural" enum value for OrientationLockType §6.
Natural §2.1
onchange attribute for ScreenOrientation §5.
orientation attribute for Screen §4.
OrientationLockType enum §6.
[[orientationPendingPromise]] internal slot for Document §3.1
OrientationType enum §7.
"portrait" enum value for OrientationLockType §6.
Portrait §2.1
portrait-primary
- enum value for OrientationLockType §6.
- enum value for OrientationType §7.
portrait-secondary
- enum value for OrientationLockType §6.
- enum value for OrientationType §7.
pre-lock conditions §5.2
Primary §2.1
reject and nullify the current lock promise §8.2
screen orientation change steps §8.4
screen orientation values lists §2.2
screen orientations §2.1
ScreenOrientation interface §5.
Secondary §2.1
type attribute for ScreenOrientation §5.
[[type]] internal slot for ScreenOrientation §5.1
unlock method for ScreenOrientation §5.
unlock the screen orientation §2.

[APPMANIFEST] defines the following:
- display mode
- installed web application
- orientation (for manifest)
[CSSOM-VIEW] defines the following:
- Screen interface
[DOM] defines the following:
- Document interface
- documents
- EventTarget interface
- Fire an event
[HTML] defines the following:
- active document (for navigable)
- associated Document
- browsing context
- browsing context (for Document)
- descendant navigables (for Document)
- DOM manipulation task source
- event handler
- event handler event type
- event handler IDL attribute
- EventHandler
- fully active (for Document)
- fully active descendant of a top-level traversable with user attention (for Document)
- in parallel
- Queue a global task
- Queue a task
- relevant global object
- sandboxed orientation lock browsing context flag
- top-level browsing context
- top-level traversable
- unloading document cleanup steps
- user interaction task source
- visibility state (for Document)
- Window interface
[INFRA] defines the following:
- Assert
- For each (for list)
- ordered set
- user agent
[WCAG21] defines the following:
- essential
- Orientation Success Criterion
[WEBIDL] defines the following:
- a new promise
- a promise rejected with
- AbortError exception
- DOMException interface
- DOMString interface
- exception
- [Exposed] extended attribute
- InvalidStateError exception
- NotAllowedError exception
- NotSupportedError exception
- Promise interface
- reject
- resolve
- [SameObject] extended attribute
- SecurityError exception
- this
- throw (for exception)
- undefined type
- unsigned short type

Thanks Christophe Dumez, Anne van Kesteren, Chundong Wang, Fuqiao Xue, and Chaals McCathie Nevile for their useful comments.

Special thanks to Chris Jones and Jonas Sicking for their contributions to the initial design of this API.

[appmanifest]: Web Application Manifest. Marcos Caceres; Daniel Murphy; Christian Liebel. W3C. 23 July 2026. W3C Working Draft. URL: https://www.w3.org/TR/appmanifest/
[cssom-view]: CSSOM View Module. Simon Fraser; Emilio Cobos Álvarez. W3C. 16 September 2025. W3C Working Draft. URL: https://www.w3.org/TR/cssom-view-1/
[dom]: DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[fullscreen]: Fullscreen API Standard. Philip Jägenstedt. WHATWG. Living Standard. URL: https://fullscreen.spec.whatwg.org/
[HTML]: HTML Standard. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[infra]: Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/info/rfc2119/
[RFC8174]: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/info/rfc8174/
[WCAG21]: Web Content Accessibility Guidelines (WCAG) 2.1. Michael Cooper; Andrew Kirkpatrick; Joshue O'Connor; Alastair Campbell. W3C. 6 May 2025. W3C Recommendation. URL: https://www.w3.org/TR/WCAG21/
[WEBIDL]: Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/

Abstract

Status of This Document

Table of Contents