+Group: WHATWG +Status: RD +Date: 2023-07-17 +H1: Fullscreen API +Shortname: fullscreen +Text Macro: TWITTER fullscreenapi +Text Macro: LATESTRD 2023-07 +Abstract: The Fullscreen API standard defines an API for elements to display themselves fullscreen. +Translation: ja https://triple-underscore.github.io/fullscreen-ja.html +Markup Shorthands: css no ++ +
+spec:dom + type:dfn; for:/; text:element + type:interface; text:Document +spec:infra + type:dfn; for:set; text:for each + type:dfn; text:string +spec:css-position-4 + type:selector; text: ::backdrop + type:dfn; text:top layer ++ +
+urlPrefix: https://w3c.github.io/screen-orientation/#dfn- + type: dfn + text: triggered by a user generated orientation change ++ +
+{
+ "CSS": {
+ "aliasOf": "CSS2"
+ },
+ "SVG": {
+ "aliasOf": "SVG11"
+ }
+}
+
+
+
+
+This specification depends on the Infra Standard. [[!INFRA]] + +
Most terminology used in this specification is from CSS, DOM, HTML, and Web IDL. [[!CSS]] +[[!DOM]] [[!HTML]] [[!WEBIDL]] + + + +
All elements have an associated fullscreen flag. Unless stated otherwise it is +unset. + +
All <{iframe}> elements have an associated iframe fullscreen flag. Unless +stated otherwise it is unset. + +
All documents have an associated fullscreen element. The +fullscreen element is the topmost element in the document's +top layer whose fullscreen flag is set, if any, and null otherwise. + +
All documents have an associated list of pending fullscreen events, which +is an ordered set of (string, element) tuples. It is initially empty. + +
To fullscreen an element: + +
Run hide all popovers given element's node document. + +
Set element's fullscreen flag. + +
Remove from the top layer immediately given element. + +
To unfullscreen an element, unset element's +fullscreen flag and iframe fullscreen flag (if any), and +remove from the top layer immediately given element. + +
To unfullscreen a document, +unfullscreen all elements, within document's +top layer, whose fullscreen flag is set. + +
To fully exit fullscreen a document document, run these steps: + +
If document's fullscreen element is null, terminate these steps. + +
Unfullscreen elements whose fullscreen flag is + set, within document's top layer, except for document's + fullscreen element. + +
Exit fullscreen document. +
Whenever the removing steps run with a removedNode, run +these steps: + +
Let document be removedNode's node document. + +
Let nodes be removedNode's + shadow-including inclusive descendants that have their fullscreen flag set, in + shadow-including tree order. + +
For each node in nodes: + +
If node is document's fullscreen element, + exit fullscreen document. + +
Otherwise, unfullscreen node. + +
If document's top layer contains node, + remove from the top layer immediately given node. + +
Other specifications can add and remove elements from top layer, so + node might not be document's fullscreen element. For example, + node could be an open <{dialog}> element. +
Whenever the unloading document cleanup steps run with a document, +fully exit fullscreen document. + +
Fullscreen is supported if there is no previously-established user preference, +security risk, or platform limitation. + +
To run the fullscreen steps for a document document, run these +steps: + +
Let pendingEvents be document's + list of pending fullscreen events. + +
Empty document's list of pending fullscreen events. + +
For each (type, element) in pendingEvents: + +
Let target be element if element is connected + and its node document is document, and otherwise let target be + document. + +
Fire an event named type, with its {{Event/bubbles}} and + {{Event/composed}} attributes set to true, at target. +
These steps integrate with the event loop defined in HTML. [[!HTML]] +
+enum FullscreenNavigationUI {
+ "auto",
+ "show",
+ "hide"
+};
+
+dictionary FullscreenOptions {
+ FullscreenNavigationUI navigationUI = "auto";
+};
+
+partial interface Element {
+ Promise<undefined> requestFullscreen(optional FullscreenOptions options = {});
+
+ attribute EventHandler onfullscreenchange;
+ attribute EventHandler onfullscreenerror;
+};
+
+partial interface Document {
+ [LegacyLenientSetter] readonly attribute boolean fullscreenEnabled;
+ [LegacyLenientSetter, Unscopable] readonly attribute boolean fullscreen; // historical
+
+ Promise<undefined> exitFullscreen();
+
+ attribute EventHandler onfullscreenchange;
+ attribute EventHandler onfullscreenerror;
+};
+
+partial interface mixin DocumentOrShadowRoot {
+ [LegacyLenientSetter] readonly attribute Element? fullscreenElement;
+};
+
+
+
+promise = element . requestFullscreen([options])
+ document . {{Document/fullscreenEnabled}}
+ Returns true if document has the ability to display elements fullscreen + and fullscreen is supported, or false otherwise. + +
promise = document . {{Document/exitFullscreen()}}
+ Stops document's fullscreen element from being displayed fullscreen and + resolves promise when done. + +
document . {{DocumentOrShadowRoot/fullscreenElement}}
+ Returns document's fullscreen element. + +
shadowroot . {{DocumentOrShadowRoot/fullscreenElement}}
+ Returns shadowroot's fullscreen element. +
A fullscreen element ready check for an element element returns true +if all of the following are true, and false otherwise: + +
element is connected. + +
element's node document is allowed to use the "fullscreen" feature.
+
+
+
element namespace is not the HTML namespace or + element's popover visibility state is hidden. +
The requestFullscreen(options) method steps
+are:
+
+
Let pendingDoc be this's node document. + +
Let promise be a new promise. + +
If pendingDoc is not fully active, then reject promise with a + {{TypeError}} exception and return promise. + +
Let error be false. + +
If any of the following conditions are false, then set error to true: + +
This's namespace is the HTML namespace or
+ this is an
+ SVG svg or
+ MathML math
+ element. [[!SVG]] [[!MATHML]]
+
+
This is not a <{dialog}> element. + +
The fullscreen element ready check for this returns true. + +
This's relevant global object has transient activation or the + algorithm is triggered by a user generated orientation change. +
If error is false, then consume user activation given + pendingDoc's relevant global object. + +
Return promise, and run the remaining steps in parallel. + +
If error is false, then resize pendingDoc's node navigable's + top-level traversable's active document's viewport's + dimensions, optionally taking into account + options["{{FullscreenOptions/navigationUI}}"]: + + +
| value | +viewport dimensions | +
|---|---|
"hide" |
+ full dimensions of the screen of the output device | +
"show" |
+ dimensions of the screen of the output device clamped to allow the user agent to show page navigation controls | +
"auto" |
+ user-agent defined, but matching one of the above | +
Optionally display a message how the end user can revert this. + +
If any of the following conditions are false, then set error to true: + +
This's node document is pendingDoc. + +
The fullscreen element ready check for this returns true. + +
If error is true: + +
Append ({{fullscreenerror}}, this) to + pendingDoc's list of pending fullscreen events. + +
Reject promise with a {{TypeError}} exception and terminate these + steps. +
Let fullscreenElements be an ordered set initially consisting of + this. + +
While true: + +
Let last be the last item of fullscreenElements. + +
Let container be last's node navigable's + container. + +
If container is null, then break. + +
Append container to fullscreenElements. +
For each element in fullscreenElements: + +
Let doc be element's node document. + +
If element is doc's fullscreen element, continue. + +
No need to notify observers when nothing has changed. + +
If element is this and this is an <{iframe}> + element, then set element's iframe fullscreen flag. + +
Fullscreen element within doc. + +
Append ({{fullscreenchange}}, element) to + doc's list of pending fullscreen events. +
The order in which elements are fullscreened + is not observable, because run the fullscreen steps is invoked in tree order. + +
Resolve promise with undefined. +
Implementations with out-of-process navigables are left as an exercise +to the reader. Input welcome on potential improvements. +
The fullscreenEnabled getter steps are to return
+true if this is allowed to use the "fullscreen" feature and fullscreen is supported, and
+false otherwise.
+
+
The fullscreen getter steps are to return false if
+this's fullscreen element is null, and true otherwise.
+
+
Use the {{DocumentOrShadowRoot/fullscreenElement}} attribute instead. + +
The
+fullscreenElement
+getter steps are:
+
+
If this is a shadow root and its host is not + connected, then return null. + +
Let candidate be the result of retargeting fullscreen element + against this. + +
If candidate and this are in the same tree, then return + candidate. + +
Return null. +
A document is said to be a simple fullscreen document if there is exactly one +element in its top layer that has its fullscreen flag set. + +
A document with two elements in its top layer can be a +simple fullscreen document. For example, in addition to the fullscreen element there +could be an open <{dialog}> element. + +
To collect documents to unfullscreen given doc, run these steps: + +
Let docs be an ordered set consisting of doc. + +
While true: + +
Let lastDoc be docs's last document. + +
Assert: lastDoc's fullscreen element is not null. + +
If lastDoc is not a simple fullscreen document, break. + +
Let container be lastDoc's node navigable's + container. + +
If container is null, then break. + +
If container's iframe fullscreen flag is set, break. + +
Append container's node document to docs. +
Return docs. + +
This is the set of documents for which the fullscreen element will be + unfullscreened, but the last document in docs might + have more than one element in its top layer with the fullscreen flag set, + in which case that document will still remain in fullscreen. +
To exit fullscreen a document doc, run these steps: + +
Let promise be a new promise. + +
If doc is not fully active or doc's fullscreen element + is null, then reject promise with a {{TypeError}} exception and return + promise. + +
Let resize be false. + +
Let docs be the result of + collecting documents to unfullscreen given + doc. + + +
Let topLevelDoc be doc's node navigable's + top-level traversable's active document. + + +
If topLevelDoc is in docs, and it is a + simple fullscreen document, then set doc to topLevelDoc and + resize to true. + +
If doc's fullscreen element is not connected: +
Append ({{fullscreenchange}}, doc's + fullscreen element) to doc's + list of pending fullscreen events. +
Return promise, and run the remaining steps in parallel. + +
Run the [=fully unlock the screen orientation steps=] with doc. + +
If resize is true, resize doc's viewport to its "normal" dimensions. + +
If doc's fullscreen element is null, then resolve promise with + undefined and terminate these steps. + +
Let exitDocs be the result of + collecting documents to unfullscreen given + doc. + + +
Let descendantDocs be an ordered set consisting of doc's + descendant navigables' active documents whose + fullscreen element is non-null, if any, in tree order. + + +
For each exitDoc in exitDocs: + +
Append ({{fullscreenchange}}, exitDoc's + fullscreen element) to exitDoc's list of pending fullscreen events. + +
If resize is true, unfullscreen + exitDoc. + +
Otherwise, unfullscreen exitDoc's + fullscreen element. +
For each descendantDoc in descendantDocs: + +
Append ({{fullscreenchange}}, descendantDoc's + fullscreen element) to descendantDoc's + list of pending fullscreen events. + +
The order in which documents are unfullscreened + is not observable, because run the fullscreen steps is invoked in tree order. + +
Resolve promise with undefined. +
The exitFullscreen() method steps are to return the
+result of running exit fullscreen on this.
+
+
The following are the event handlers (and their corresponding +event handler event types) that must be supported by {{Element}} and {{Document}} objects as +event handler IDL attributes: + +
| event handler + | event handler event type + |
|---|---|
onfullscreenchange
+ | fullscreenchange
+ |
onfullscreenerror
+ | fullscreenerror
+ |
These are not supported by {{ShadowRoot}} or {{Window}} objects, and there are no +corresponding event handler content attributes for {{Element}} objects in any namespace. + + + +
User agents are encouraged to implement native media fullscreen controls in terms of +{{Element/requestFullscreen()}} and {{Document/exitFullscreen()}}. + +
If the end user instructs the user agent to end a fullscreen session initiated via +{{Element/requestFullscreen()}}, fully exit fullscreen given the +top-level traversable's active document. + +
The user agent may end any fullscreen session without instruction from the end user +or call to {{Document/exitFullscreen()}} whenever the user agent deems it necessary. + + + +
This section is to be interpreted equivalently to the Rendering section of HTML. [[!HTML]] + + +
:fullscreen pseudo-classThe :fullscreen pseudo-class must match any
+element element for which one of the following conditions is true:
+
+
element's fullscreen flag is set. + +
element is a shadow host and the result of retargeting its + node document's fullscreen element against element is element. +
This makes it different from the +{{DocumentOrShadowRoot/fullscreenElement}} API, which returns the topmost fullscreen element. + +
+@namespace "http://www.w3.org/1999/xhtml";
+
+*|*:not(:root):fullscreen {
+ position:fixed !important;
+ inset:0 !important;
+ margin:0 !important;
+ box-sizing:border-box !important;
+ min-width:0 !important;
+ max-width:none !important;
+ min-height:0 !important;
+ max-height:none !important;
+ width:100% !important;
+ height:100% !important;
+ transform:none !important;
+
+ /* intentionally not !important */
+ object-fit:contain;
+}
+
+iframe:fullscreen {
+ border:none !important;
+ padding:0 !important;
+}
+
+*|*:not(:root):fullscreen::backdrop {
+ background:black;
+}
+
+
+
+
+This specification defines a policy-controlled feature identified by the string
+"fullscreen". Its default allowlist is
+'self'.
+
+
A document's permissions policy determines whether any content in that +document is allowed to go fullscreen. If disabled in any document, no content in the document will +be allowed to use fullscreen. + +
The <{iframe/allowfullscreen}> attribute of the HTML <{iframe}> element affects the container
+policy for any document nested in that iframe. Unless overridden by the <{iframe/allow}>
+attribute, setting <{iframe/allowfullscreen}> on an iframe is equivalent to <iframe
+allow="fullscreen *">, as described in
+[[permissions-policy#iframe-allowfullscreen-attribute]].
+
User agents should ensure, e.g. by means of an overlay, that the end user is aware something is +displayed fullscreen. User agents should provide a means of exiting fullscreen that always works and +advertise this to the user. This is to prevent a site from spoofing the end user by recreating the +user agent or even operating system environment when fullscreen. See also the definition of +{{Element/requestFullscreen()}}. + +
To enable content in a child navigable to go fullscreen, it needs to be specifically
+allowed via permissions policy, either through the <{iframe/allowfullscreen}> attribute of the HTML
+<{iframe}> element, or an appropriate declaration in the <{iframe/allow}> attribute of the HTML
+<{iframe}> element, or through a `Permissions-Policy` HTTP header
+delivered with the document through which it is nested.
+
+
This prevents e.g. content from third parties to go fullscreen without explicit permission. + + + +
Many thanks to Robert O'Callahan for designing the initial model and being awesome. + + +
Thanks to +Andy Earnshaw, +Changwan Hong, +Chris Pearce, +Darin Fisher, +Dave Tapuska, +fantasai, +Giuseppe Pascale, +Glenn Maynard, +Ian Clelland, +Ian Hickson, +Ignacio Solla, +João Eiras, +Josh Soref, +Kagami Sascha Rosylight, +Matt Falkenhagen, +Mihai Balan, +Mounir Lamouri, +Øyvind Stenhaug, +Pat Ladd, +Rafał Chłodnicki, +Riff Jiang, +Rune Lillesveen, +Sigbjørn Vik, +Simon Pieters, +Tab Atkins-Bittner, +Takayoshi Kochi, +Theresa O'Connor, +triple-underscore, +Vincent Scheib, and +Xidorn Quan +for also being awesome. + +
This standard is edited by Philip Jägenstedt +(Google, +philip@foolip.org). It was originally written by +Anne van Kesteren +(Apple, annevk@annevk.nl). +Tantek Çelik +(Mozilla, +tantek@cs.stanford.edu) sorted out legal hassles.