Copyright © 2023 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
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. The API also allows for the screen orientation to be locked under certain preconditions. This is particularly useful for applications such as computer games, where users physically rotate the device, but the screen orientation itself should not change.
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 technical reports index at https://www.w3.org/TR/.
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 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 which 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 12 June 2023 W3C Process Document.
This section is non-normative.
In this example clicking the "Lock" button requests to go into fullscreen and then locks the screen to the opposite orientation. clicking the "unlock" button unlocks the screen.
<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:
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.
The screen of the output device has the following associated concepts:
OrientationLockType
, to which the screen is locked, or
null
when unlocked.
OrientationType
.
The screen orientation values lists below standardize the angles associated with each screen orientation type for screens with different natural orientations:
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.
|
WebIDLpartial 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
).
WebIDL[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.
|
When the lock
()
method is invoked with OrientationLockType
orientation, the user agent MUST run the
following steps.
The user agent MAY require a document and its associated browsing context to meet one or more pre-lock conditions in order to lock the screen orientation. See 10. Interaction with Web Application Manifest and 9. Interaction with Fullscreen API.
Document
.
NotSupportedError
" DOMException
and abort these steps.
[[orientationPendingPromise]]
is not null
, reject and nullify the current lock promise of document with an
"AbortError
".
[[orientationPendingPromise]]
to a new promise.
[[orientationPendingPromise]]
.
When the unlock
()
method is invoked, the user agent MUST run
the following steps:
Document
.
null
, return
undefined
.
[[orientationPendingPromise]]
is not
null
, reject and nullify the current lock promise of document
with an "AbortError
".
null
to document.
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:
InvalidStateError
" DOMException
.
SecurityError
" DOMException
.
SecurityError
" DOMException
.
When getting, the angle
attribute returns this's
[[angle]]
.
The onchange
attribute is an event handler IDL attribute for
the onchange
event handler, whose event handler event type
is change.
WebIDLenum 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.
WebIDLenum 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:
ScreenOrientation
.
[[initialType]]
internal slot to the screen's
current orientation type.
[[type]]
internal slot to the screen's current orientation type.
[[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:
[[orientationPendingPromise]]
is not
null
.
[[orientationPendingPromise]]
.
DOMException
.
[[orientationPendingPromise]]
to
null
.
When steps require to apply orientation lock of
OrientationLockType?
orientation to Document
document, the
user agent MUST perform do the following steps:
[[orientationPendingPromise]]
is not
null
, reject and nullify the current lock promise of document
with an "AbortError
".
[[orientationPendingPromise]]
is null
,
continue.
AbortError
".
[[orientationPendingPromise]]
is
not null
, reject and nullify the current lock promise of
document with an "AbortError
" and abort these steps.
null
, unlock the screen orientation.
null
.
[[orientationPendingPromise]]
is not null
,
reject and nullify the current lock promise of
document with a "NotSupportedError
".
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.
[[orientationPendingPromise]]
.
[[orientationPendingPromise]]
to
null
.
null
, resolve promise with
undefined
.
When a user-agent determines that the screen's orientation has changed for a top-level browsing context, or the user moves the top-level browsing context to a different screen, then run the screen orientation change steps with the top-level browsing context's active document.
The screen orientation change steps for
Document
document are as follows:
ScreenOrientation
.
[[type]]
and angle is equal to
screenOrientation's [[angle]]
, abort these
steps.
[[angle]]
to
angle.
[[type]]
to
type.
[HTML]'s update the visibility state runs the screen orientation change steps.
Whenever the unloading document cleanup steps run with a document, the user agent MUST run the following steps:
The fully unlock the screen orientation steps
for Document
document are as follows:
[[orientationPendingPromise]]
is not
null
, reject and nullify the current lock promise of document
with an "AbortError
".
null
to topDocument.
A user agent SHOULD restrict the use of lock
()
to
simple fullscreen documents as a pre-lock condition. [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 vector. The following mitigation help protect a user's privacy by not revealing how a device is being held, and also prevents the secondary orientation type and associated angles from being user for fingerprinting purposes.
To resist fingerprinting (e.g., in private browsing), user agents MAY:
[[initialType]]
.
type
getter to
"portrait-primary
" or
"landscape-primary
". The screen aspect ratio
determines which is returned.
[[initialType]]
, return 0
for the
angle
getter. Otherwise, return 90
.
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.
WebIDLpartial 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
"
};
angle
attribute for ScreenOrientation
§5.[[angle]]
internal slot for ScreenOrientation
§5.1"any"
enum value for OrientationLockType
§6.[[initialType]]
internal slot for ScreenOrientation
§5.1"landscape"
enum value for OrientationLockType
§6.lock
method for ScreenOrientation
§5."natural"
enum value for OrientationLockType
§6.onchange
attribute for ScreenOrientation
§5.orientation
attribute for Screen
§4.OrientationLockType
enum
§6.[[orientationPendingPromise]]
internal slot for Document
§3.1OrientationType
enum
§7."portrait"
enum value for OrientationLockType
§6.ScreenOrientation
interface
§5.type
attribute for ScreenOrientation
§5.[[type]]
internal slot for ScreenOrientation
§5.1unlock
method for ScreenOrientation
§5.manifest
)
Screen
interface
Document
interface
EventTarget
interface
Document
)
EventHandler
Document
)
Document
)
Window
interface
list
)
AbortError
exception
DOMException
interface
DOMString
interface
[Exposed]
extended attribute
InvalidStateError
exception
NotSupportedError
exception
Promise
interface
[SameObject]
extended attribute
SecurityError
exception
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.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: