The Screen Orientation API

W3C Working Draft

This version:
https://www.w3.org/TR/2020/WD-screen-orientation-20200122/
Latest published version:
https://www.w3.org/TR/screen-orientation/
Latest editor's draft:
https://w3c.github.io/screen-orientation/
Test suite:
https://w3c-test.org/screen-orientation/
Previous version:
https://www.w3.org/TR/2019/WD-screen-orientation-20191102/
Editors:
Mounir Lamouri (Google Inc.)
Marcos Cáceres (Mozilla)
Johanna Herman (Invited Expert)
Participate:
GitHub w3c/screen-orientation
File a bug
Commit history
Pull requests
Browser support:
caniuse.com

Abstract

The Screen Orientation API provides the ability to read the screen orientation type and angle, to be informed when the screen orientation changes, and to lock the screen to a specific orientation.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. 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. This document is intended to become a W3C Recommendation.

GitHub Issues are preferred for discussion of this specification.

Publication as a Working Draft does not imply endorsement by the W3C Membership. 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 1 March 2019 W3C Process Document.

1. Introduction

This section is non-normative.

For web applications, the Screen Orientation API exposes the type and angle of a device's current screen orientation, and can provide notification if the device's orientation changes. This allows web applications to programmatically adapt the user experience for many possible screen orientations (in concert with CSS). The API also allows locking the screen to a particular orientation. This is useful in applications such as computer games where users physically rotate the device but the screen orientation itself mustn't change.

1.1 Goals

1.2 Examples

This section is non-normative.

1.2.1 Locking to a specific orientation and unlocking

In this example, clicking the "Lock" button makes a request to go into fullscreen and then lock the screen to the opposite orientation. Pressing the "Unlock" button unlocks the screen so it rotates if the user turns the device.

The developer console logs the change in orientation type and angle.

<script>
function fullScreenCheck() {
  if (document.fullscreenElement) return;
  return document.documentElement.requestFullscreen();
}

function updateDetails(lockButton) {
  const buttonOrientation = getOppositeOrientation();
  lockButton.textContent = `Lock to ${buttonOrientation}`;
}

function getOppositeOrientation() {
  const { type } = screen.orientation;
  return type.startsWith("portrait") ? "landscape" : "portrait";
}

async function rotate(lockButton) {
  try {
    await fullScreenCheck();
  } catch (err) {
    console.error(err);
  }
  const newOrientation = getOppositeOrientation();
  await screen.orientation.lock(newOrientation);
  updateDetails(lockButton);
}

function show() {
  const { type, angle } = screen.orientation;
  console.log(`Orientation type is ${type} & angle is ${angle}.`);
}

screen.orientation.addEventListener("change", () => {
  show();
  updateDetails(document.getElementById("button"));
});

window.addEventListener("load", () => {
  show();
  updateDetails(document.getElementById("button"));
});
</script>

<button onclick="rotate(this)" id="button">
  Lock
</button>
<button onclick="screen.orientation.unlock()">
  Unlock
</button>

1.2.2 Locking the screen before calling a function

This example waits to go into fullscreen, then locks to landscape before calling ready().

<script>
function ready() {
  const { type } = screen.orientation;
  console.log(`Fullscreen and locked to ${type}. Ready!`);
}

async function start() {
  await document.body.requestFullscreen();
  await screen.orientation.lock("landscape");
  ready();
}
</script>
<button onclick="start()">
  Start
</button>

1.2.3 Alerting the user if the API is not supported

In this example, if the Screen Orientation API is not supported, or the screen orientation lock() rejects, the user is alerted to rotate their screen manually to landscape.

<script>
function start() {
  /* Start application when in correct orientation */
}
async function rotate() {
  try {
    await screen.orientation.lock("landscape");
    start();
  } catch (err) {
    console.error(err);
  }
  const matchLandscape = matchMedia("(orientation: landscape)");
  if (matchLandscape.matches) return start();
  addEventListener("orientationchange", function listener() {
    matchLandscape.addListener(function mediaChange(e) {
      if (!e.matches) return;
      removeEventListener("orientationchange", listener);
      matchLandscape.removeListener(mediaChange);
      start();
    });
  });
  alert("To start, please rotate your screen to landscape.");
}
</script>
<button onclick="start()">
  Start
</button>

2. Extensions to the Screen interface

The CSSOM View Module specification defines the Screen interface, which this specification extends:

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

2.1 orientation attribute

The Screen.orientation attribute is an instance of ScreenOrientation. This attribute provides the current orientation, current angle and whether there was an onchange event. The user agent MUST run the update the orientation information algorithm steps to initialize the values and return the Screen.orientation attribute.

3. ScreenOrientation interface

WebIDL[Exposed=Window]
interface ScreenOrientation : EventTarget {
  Promise<void> lock(OrientationLockType orientation);
  void 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"
};

The OrientationLockType enum represents the screen orientations to which a screen can be locked: the "any" enum value represents the any orientation, the "natural" enum represents the natural orientation, the "landscape" enum represents the landscape orientation, the "portrait" enum represents the portrait orientation, the "portrait-primary" enum represents the portrait-primary orientation, the "portrait-secondary" enum represents the portrait-secondary orientation, the "landscape-primary" enum represents the landscape-primary orientation, and the "landscape-secondary" enum represents the landscape-secondary orientation.

The OrientationType enum represents the actual current screen orientation that the screen is in irrespective of which lock is applied: the "portrait-primary" enum represents the portrait-primary orientation, the "portrait-secondary" enum represents the portrait-secondary orientation, the "landscape-primary" enum represents the landscape-primary orientation, and the "landscape-secondary" enum represents the landscape-secondary orientation.

3.1 lock() method: Lock screen to a specific orientation

When the lock() method is invoked, the user agent MUST run the apply an orientation lock steps to the responsible document using orientation.

3.2 unlock() method: Unlock screen to default orientation

When the unlock() method is invoked, the user agent MUST run the steps to lock the orientation of the responsible document to its default orientation.

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

unlock() does not return a promise because it is equivalent to locking to the default 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.

Issue 104: Promise for unlock()? question

I understand that this might not be possible from the note -

unlock() does not return a Promise because it is equivalent to locking to the default 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.

I am working on building an app that uses WebVR. Entering VR mode requires going fullscreen and then locking orientation to landscape. This works perfectly.

However exiting this mode when phone is in portrait orientation, on tested Android devices, results in the browser bar and menu disappearing and a large white space appearing under the app. Dragging down on the screen reveals the browser bar and covers the white space, you can not then drag back up.

orientation unlock issue

I've overcome this issue using the following code

screen.orientation.unlock();
setTimeout( () => {
    fullscreen.exit();
}, 0 );

A cleaner solution would be something like -

screen.orientation.unlock().then( () => {
    fullscreen.exit();
});

3.3 type attribute: Get current orientation

When getting the type attribute, the user agent MUST return the responsible document's current orientation type.

3.4 angle attribute: Get orientation angle

When getting the angle attribute, the user agent MUST return the responsible document's current orientation angle.

Note: What does the value given for angle represent?

angle represents how far the user has turned the device counterclockwise from the natural orientation. When the device is rotated 90° counterclockwise, the screen compensates by rotating 90° clockwise, so angle returns 90.

The screen orientation values table shows how the angle changes depending on the how the device is rotated.

The value returned by this property is always in the range 0-359. It never returns negative values.

3.5 onchange attribute: Handle orientation changes

The onchange attribute is an event handler whose corresponding event handler event type is "change".

4. Extensions to the Document interface

4.1 Internal Slots

Internal Slot Description
[[orientationLock]] The [[orientationLock]] represents a document's orientation lock as an ordered set of OrientationType.
[[defaultOrientation]] An ordered set of orientations to which the screen orientation is locked when not explicitly locked by this API or any other means.
[[orientationPendingPromise]] Either null or a Promise. When assigned a Promise, that promise represents a request to lock the screen to one of the supported orientations. The promise resolves after locking the orientation succeeds or rejects if locking fails.

5. Concepts

The term screen is equivalent to the screen of the output device associated to the Window, as per [CSSOM-VIEW].

Algorithms defined in this specification assume that for each document there is an [[orientationPendingPromise]].

5.1 Screen orientation types and locks

Landscape-primary is an orientation where the screen width is greater than the screen height. If the device's natural orientation is landscape, then it is in landscape-primary when held in that position. If the device's natural orientation is portrait, the user agent sets landscape-primary from the two options as shown in the screen orientation values table.

Landscape-secondary is an orientation where the screen width is greater than the screen height. If the device's natural orientation is landscape, it is in landscape-secondary when rotated 180º from its natural orientation. If the device's natural orientation is portrait, the user agent sets landscape-secondary from the two options as shown in the screen orientation values table.

Portrait-primary is an orientation where the screen width is less than or equal to the screen height. If the device's natural orientation is portrait, then it is in portrait-primary when held in that position. If the device's natural orientation is landscape, the user agent sets portrait-primary from the two options as shown in the screen orientation values table.

Portrait-secondary is an orientation where the screen width is less than or equal to the screen height. If the device's natural orientation is portrait, then it is in portrait-secondary when rotated 180º from its natural position. If the device's natural orientation is landscape, the user agent sets portrait-secondary from the two options as shown in the screen orientation values table.

Portrait is an orientation where the screen width is less than or equal to the screen height and depending on platform convention locking the screen to portrait can represent portrait-primary, portrait-secondary or both.

Landscape is an orientation where the screen width is greater than the screen height and depending on platform convention locking the screen to landscape can represent landscape-primary, landscape-secondary or both.

Natural is an orientation that refers to either portrait-primary or landscape-primary depending on the device's usual orientation. This orientation is usually provided by the underlying operating system.

Any is an orientation that means the screen can be locked to any one of portrait-primary, portrait-secondary, landscape-primary and landscape-secondary.

The default orientation is the set of orientations to which the screen is locked when there is no current orientation lock. This orientation is determined by the device's operating system, or the user agent (e.g., § 6.2 Interaction with Web Application Manifest ), or controlled by the end-user.

Issue 150: Definition of default orientation

Currently default orientation is defined with the following:

        A <a>document</a>'s <dfn>default orientation</dfn> is the set of
          orientations to which the screen orientation is locked when it is not
          explicitly locked by this API or any other means.

It would be great to get some clarification on why default orientation is a set? From looking at the android docs it looks like the system decides on one orientation if none is specified.

@mounirlamouri Could you please explain this further?

Relates to #104

5.2 Reading the screen orientation

All documents have a current orientation type and a current orientation angle. Both of them SHOULD be initialized when the document is created, otherwise they MUST be initialized the first time they are accessed and before their value is read. The user agent MUST update the orientation information of the document to initialize them.

For a given document, the current orientation type and the current orientation angle are strongly linked in the sense that for any given type, there will be a specific angle associated.

One primary orientation will always be determined by the natural orientation of the device and this will then determine the secondary value of its related orientation.

For example a device held in its natural portrait orientation would have a current orientation of portrait-primary and its portrait-secondary orientation would be its position when rotated 180°.

The user agent can associate the other *-primary and *-secondary values at will. For example, it can be based on the device preferred angles, the user's preferred orientations or the current orientation when the application starts.

The screen orientation values table presents the possible orientation types: portrait-primary, portrait-secondary, landscape-primary and landscape-secondary. The table shows the primary and secondary values that are determined by the device's natural orientation and the possibilities available to the user agent for setting the other primary and secondary orientation values.

The screen orientation values table
Natural Orientation Primary Orientation 1 Secondary Orientation 1 Primary Orientation 2 Secondary Orientation 2
Portrait portrait-primary
angle 0
portrait-secondary
angle 180
landscape-primary
User agent to set at either angle 90 or angle 270
landscape-secondary
Set at the angle not used for landscape-primary
Landscape landscape-primary
angle 0
landscape-secondary
angle 180
portrait-primary
User agent to set at either angle 90 or angle 270
portrait-secondary
Set at the angle not used for portrait-primary

Once the user agent has set the primary and secondary values from the options in the screen orientation values table, the current orientation type and the current orientation angle relation MUST be kept consistent for any given document.

Best Practice 1: ScreenOrientation.angle and ScreenOrientation.type relationship

Never assume any cross-devices relationship between the screen orientation type and the screen orientation angle. Any assumption would be wrong given that a device might have 90 and 270 as the angles for landscape types but another device will have 0 and 180, depending on its natural orientation. Instead, it is recommended to check during runtime the relationship between angle and type.

5.3 Locking the screen orientation

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. For example, a user agent might require a document's top-level browsing context to be fullscreen (see § 6.1 Interaction with Fullscreen API ) in order to allow an orientation lock.

The user agent MAY reject all attempts to lock the screen orientation if the platform conventions do not expect applications to be able to change the screen orientation. For example, on most desktop platforms, applications can not change the screen orientation.

If the user agent supports locking the screen orientation, it MUST allow the screen to be locked to all of the states of the OrientationLockType enum.

The [[orientationLock]] internal slot represents the document's orientation lock.

An orientation lock is in place when the screen has successfully been locked to a specific orientation.

5.3.1 Locking to the default orientation

From the perspective of a document, locking to the default orientation is equivalent to unlocking because it means that it no longer has a lock applied.

Note: Who controls the default orientation?

This does not mean that the [[defaultOrientation]] will only contain the item any. The default orientation is likely device-specific and [[defaultOrientation]] could for example contain portrait-primary and/or landscape-primary. Alternatively, the user could restrict the default orientation to a specific orientation via some OS or browser level preference for accessibility reasons. The user agent can also set the default orientation e.g., § 6.2 Interaction with Web Application Manifest .

6. Interactions with other specifications

This section explains how this specification interacts with other related specifications of the platform.

6.1 Interaction with Fullscreen API

As a pre-lock condition, a user agent MAY restrict locking the screen orientation exclusively to when the top-level browsing context's document's is full screen. When that pre-lock condition applies, whenever the document's fullscreen element is empty and a screen orientation lock is applied, the user agent MUST lock the orientation of the document to the document's default orientation.

Issue
This section could be improved if the [FULLSCREEN] specification had a hook for when the document is no longer fullscreen. See issue 62.

6.2 Interaction with Web Application Manifest

This section is non-normative.

The Web App Manifest allows web applications to set the document's default orientation.

6.3 Interaction with CSS Device Adaptation

This section is non-normative.

The CSS Device Adaptation Module Level 1 specification defines, independently of this document, a way to lock the screen orientation for a web page using CSS.

6.4 Interaction with Web Content Accessibility Guidelines

This section is non-normative.

The Web Content Accessibility Guidelines (WCAG) 2.1 includes a Success Criterion related to screen orientation.

​The intent of this Success Criterion is to ensure that all essential content and functionality is available regardless of the display orientation (portrait or landscape). Some websites and applications automatically set the screen to a particular display orientation and expect that users will respond by rotating their device to match.

However, some users may have their devices mounted in a fixed orientation (e.g. on the arm of a power wheelchair). Therefore, websites and applications need to support both orientations by making sure essential content and functionality is available in each orientation. While the order of content and method of functionality may have differences the content and functionality must always be available. When a particular orientation is essential, the user needs to be advised of the orientation requirements.​

7. Algorithms

7.1 Updating the orientation information

The steps to update the orientation information of a document are as follows:

  1. If the screen width is greater than the screen height, set the document's current orientation type to landscape-primary or landscape-secondary.
  2. Otherwise, if the screen width is less than or equal to the screen height, set the document's current orientation type to portrait-primary or portrait-secondary.
  3. Set the document's current orientation angle to the clockwise angle in degrees between the orientation of the viewport as it is drawn and the natural orientation of the device (i.e., the top of the physical screen). This is the opposite of the physical rotation. In other words, if a device is turned 90 degrees on the right, the current orientation angle would be 270 degrees. The screen orientation values table gives the options for each orientation and possible associated angles.

7.2 Apply an orientation lock

The steps to apply an orientation lock to a document using orientation are as follows:

  1. If the user agent does not support locking the screen orientation, return a promise rejected with a "NotSupportedError" DOMException and abort these steps.
  2. If the document's has the sandboxed orientation lock browsing context flag set, or user agent doesn't meet the pre-lock conditions to perform an orientation change, return a promise rejected with a "SecurityError" DOMException and abort these steps.
  3. Set doc's [[orientationPendingPromise]] to a newly-created promise.
  4. Return doc's [[orientationPendingPromise]] and in parallel:
    1. Let browsing contexts be the list of the descendant browsing contexts of the top-level browsing context's document.
    2. If one of the browsing contexts's document's [[orientationPendingPromise]] is not null:
      1. Let doc be the document which has a not null [[orientationPendingPromise]].
      2. Reject doc's [[orientationPendingPromise]] with "AbortError" DOMException.
      3. Set doc's [[orientationPendingPromise]] to null .
    3. Let orientations be an empty list.
    4. Depending on orientation value, do the following:
      portrait-primary or portrait-secondary or landscape-primary or landscape-secondary
      Append orientation to orientations.
      landscape
      Depending on platform convention, append landscape-primary, or landscape-secondary, or both to orientations.
      portrait
      Depending on platform convention, append portrait-primary, or portrait-secondary, or both to orientations.
      natural
      Append portrait-primary or landscape-primary to orientations such as the associated current orientation angle is 0.
      any
      Append portrait-primary, portrait-secondary, landscape-primary and landscape-secondary to orientations.
    5. Lock the orientation of the document to orientations.
    6. If locking the orientation did not result in a change of orientation, as part of the next animation frame task, resolve [[orientationPendingPromise]] with undefined and set [[orientationPendingPromise]] to null.
Note
If locking the orientation results in an orientation change, the promise will be resolved when the orientation will change as described in the § 7.5 Screen orientation change section.

7.3 Locking the orientation

The steps to lock the orientation to orientation are as follows.

  1. Set the document's [[orientationLock]] to orientations.
  2. If the active orientation lock is not the document's [[orientationLock]], abort these steps.
  3. If the active orientation lock value is equal to orientations value, abort these steps.
  4. If orientations contains only one value, run the following sub-steps:
    1. Let orientation be the value contained in orientations.
    2. Change how the viewport is drawn so that the document's current orientation type will be equal to orientation.
    3. After the change has happened, prevent the document's top-level browsing context's screen orientation from changing until those steps are run again.
    4. Abort these steps.
  5. If the document's current orientation type is not part of orientations, change how the viewport is drawn such as the document's current orientation type will be equal to one of orientations' values.
  6. Otherwise, depending on platform conventions, change how the viewport is drawn in order to make it match another screen orientation type. However, it has to be part of orientations.
  7. Allow the user to change the screen orientation to any value part of orientations and only those values until those steps are run again. The method to define the current screen orientation has to match the platform conventions.

7.4 Determining the active orientation lock

The steps to determine the active orientation lock are as follows:

  1. If there is only one top-level browsing context with a document that is visible per [PAGE-VISIBILITY], the active orientation lock is the document's [[orientationLock]].
  2. Otherwise, if there are more than one top-level browsing context with a document that is visible per [PAGE-VISIBILITY] but only one of those documents is focused, the active orientation lock is the focused document's [[orientationLock]].
  3. Otherwise, the active orientation lock SHOULD be the latest focused document's [[orientationLock]], unless stated otherwise by the platform conventions.

Whenever the active orientation lock changes, the user agent MUST run the steps to lock the orientation of the document to the document's [[orientationLock]].

Whenever a top-level browsing context is navigated, the user agent MUST lock the orientation of the document to the document's [[defaultOrientation]].

7.5 Screen orientation change

Whenever the viewport's angle changes, the user agent MUST run the following steps as part of the next animation frame task:

  1. Let browsing contexts be the list of the descendant browsing contexts of the top-level browsing context's document.
  2. For each context in browsing contexts, run the following sub-steps:
    1. Let doc be the context's active document.
    2. If doc is not visible per [PAGE-VISIBILITY], abort these steps.
    3. Update the orientation information of doc.
    4. If the orientation change was triggered by a user gesture such as the user turning the device, as opposed to a call to lock(), the task MUST be annotated with process user orientation change when running the next step.
    5. Fire an event named change at doc's Screen.orientation object.
    6. If doc's [[orientationPendingPromise]] is not null:
      1. Resolve doc's [[orientationPendingPromise]] with undefined.
      2. Set doc's [[orientationPendingPromise]] to null .

Whenever a document becomes visible per [PAGE-VISIBILITY], in other words after the now visible algorithm is run, the user agent MUST run the following substeps as part of the next animation frame task:

  1. Let type and angle be respectively the document's current orientation type and current orientation angle.
  2. Update the orientation information of the document.
  3. If type is different from the document's current orientation type or angle from the document's current orientation angle, run the following sub-steps:
    1. If the orientation change was triggered by a user gesture such as the user turning the device, as opposed to a call to lock(), the task MUST be annotated with process user orientation change when running the next step.
    2. Fire an event named change at the document's Screen.orientation object.
    3. If the document's [[orientationPendingPromise]] is not null:
      1. Resolve the document's [[orientationPendingPromise]] with undefined.
      2. Set the document's [[orientationPendingPromise]] to null.

An algorithm is triggered by a user generated orientation change if the task in which the algorithm is running is annotated with process user orientation change.

Note

Developers need to be aware that a Screen.orientation object from a document that is not visible, as per [PAGE-VISIBILITY], will not receive an orientation change event. This is to prevent unnecessary changes to layout, etc. in the non-visible web application.

Issue
This section could be improved if the [PAGE-VISIBILITY] specification had a hook for when the document becomes visible and hidden. issue 77.

8. Privacy and Security Considerations

This section is non-normative.

8.1 Access to aspects of a user’s local computing environment

The screen orientation type and angle of the device can be accessed with the API specified in this document, and can be a potential fingerprinting vector.

The screen orientation type can already be known by using the screen width and height. In practice, the additional information provided with the API concerning the angle of the device and the primary or secondary screen orientation is unlikely to be used by any competent attack.

9. Dependencies

The following concepts and interfaces are defined in [HTML]: list of the descendant browsing contexts.

The following is defined in [PAGE-VISIBILITY]: now visible algorithm.

The following is used but not defined in [FULLSCREEN]: animation frame task.

Issue
This should now be updated since the animation frame task issue is recently resolved and the timing is now defined.

10. Conformance

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.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

A. IDL Index

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

[Exposed=Window]
interface ScreenOrientation : EventTarget {
  Promise<void> lock(OrientationLockType orientation);
  void 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"
};

B. Acknowledgments

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.

C. References

C.1 Normative references

[CSSOM-VIEW]
CSSOM View Module. Simon Pieters. W3C. 17 March 2016. 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; 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/
[PAGE-VISIBILITY]
Page Visibility (Second Edition). Jatinder Mann; Arvind Jain. W3C. 29 October 2013. W3C Recommendation. URL: https://www.w3.org/TR/page-visibility/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
[WebIDL]
Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/

C.2 Informative references

[appmanifest]
Web App Manifest. Marcos Caceres; Kenneth Christiansen; Mounir Lamouri; Anssi Kostiainen; Matt Giuca; Aaron Gustafson. W3C. 9 December 2019. W3C Working Draft. URL: https://www.w3.org/TR/appmanifest/
[CSS-ADAPTATION]
CSS Device Adaptation Module Level 1. Rune Lillesveen; Florian Rivoal; Matt Rakow. W3C. 29 March 2016. W3C Working Draft. URL: https://www.w3.org/TR/css-device-adapt-1/
[WCAG21]
Web Content Accessibility Guidelines (WCAG) 2.1. Andrew Kirkpatrick; Joshue O Connor; Alastair Campbell; Michael Cooper. W3C. 5 June 2018. W3C Recommendation. URL: https://www.w3.org/TR/WCAG21/