Fullscreen API Standard

1.Terminology

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]

2.Model

Allelementshave an associatedfullscreen flag.Unless stated otherwise it is unset.

Alliframeelementshave an associatediframe fullscreen flag.Unless stated otherwise it is unset.

Alldocumentshave an associatedfullscreen element.Thefullscreen elementis the topmostelementin thedocument’stop layerwhosefullscreen flagis set, if any, and null otherwise.

Alldocumentshave an associatedlist of pending fullscreen events,which is anordered setof (string,element)tuples.It is initially empty.

Tofullscreen anelement:

LethideUntilbe the result of runningtopmost popover ancestorgivenelement,null, and false.
IfhideUntilis null, then sethideUntiltoelement’snode document.
Runhide all popovers untilgivenhideUntil,false, and true.
Setelement’sfullscreen flag.
Remove from the top layer immediatelygivenelement.
Add to the top layergivenelement.

Tounfullscreen anelement,unsetelement’sfullscreen flagandiframe fullscreen flag(if any), andremove from the top layer immediatelygivenelement.

Tounfullscreen adocument,unfullscreenallelements,withindocument’stop layer,whosefullscreen flagis set.

Tofully exit fullscreenadocumentdocument,run these steps:

Ifdocument’sfullscreen elementis null, terminate these steps.
Unfullscreen elementswhosefullscreen flagis set, withindocument’stop layer,except fordocument’sfullscreen element.
Exit fullscreendocument.

Whenever theremoving stepsrun with aremovedNode,run these steps:

LetdocumentberemovedNode’snode document.
LetnodesberemovedNode’sshadow-including inclusive descendantsthat have theirfullscreen flagset, inshadow-including tree order.
For eachnodeinnodes:
1. Ifnodeisdocument’sfullscreen element,exit fullscreendocument.
2. Otherwise,unfullscreennode.
3. Ifdocument’stop layer containsnode,remove from the top layer immediatelygivennode.
  
  Other specifications can add and remove elements fromtop layer,sonodemight not bedocument’sfullscreen element.For example,nodecould be an opendialogelement.

Whenever theunloading document cleanup stepsrun with adocument,fully exit fullscreendocument.

Fullscreen is supportedif there is no previously-established user preference, security risk, or platform limitation.

Torun the fullscreen stepsfor adocumentdocument,run these steps:

LetpendingEventsbedocument’slist of pending fullscreen events.
Emptydocument’slist of pending fullscreen events.
For each(type,element) inpendingEvents:
1. Lettargetbeelementifelementisconnectedand itsnode documentisdocument,and otherwise lettargetbedocument.
2. Fire an eventnamedtype,with itsbubblesandcomposedattributes set to true, attarget.

These steps integrate with theevent loopdefined in HTML.[HTML]

3.API

enumFullscreenNavigationUI{
"auto",
"show",
"hide"
};

dictionaryFullscreenOptions{
FullscreenNavigationUInavigationUI= "auto";
};

partialinterfaceElement{
Promise<undefined>requestFullscreen(optionalFullscreenOptionsoptions= {});

attributeEventHandleronfullscreenchange;
attributeEventHandleronfullscreenerror;
};

partialinterfaceDocument{
[LegacyLenientSetter]readonlyattributebooleanfullscreenEnabled;
[LegacyLenientSetter,Unscopable]readonlyattributebooleanfullscreen;// historical

Promise<undefined>exitFullscreen();

attributeEventHandleronfullscreenchange;
attributeEventHandleronfullscreenerror;
};

partialinterfacemixinDocumentOrShadowRoot{
[LegacyLenientSetter]readonlyattributeElement?fullscreenElement;
};

promise=element.requestFullscreen([options]): Displayselementfullscreen and resolvespromisewhen done.
When supplied,options’snavigationUImember indicates whether showing navigation UI while in fullscreen is preferred or not. If set to "show",navigation simplicity is preferred over screen space, and if set to"hide",more screen space is preferred. User agents are always free to honor user preference over the application’s. The default value "auto"indicates no application preference.
document.fullscreenEnabled: Returns true ifdocumenthas the ability to displayelementsfullscreen andfullscreen is supported,or false otherwise.
promise=document.exitFullscreen(): Stopsdocument’sfullscreen elementfrom being displayed fullscreen and resolvespromisewhen done.
document.fullscreenElement: Returnsdocument’sfullscreen element.
shadowroot.fullscreenElement: Returnsshadowroot’sfullscreen element.

Afullscreen element ready checkfor anelementelementreturns true if all of the following are true, and false otherwise:

elementisconnected.
element’snode documentisallowed to usethe "fullscreen"feature.
elementnamespaceis not theHTML namespaceorelement’spopover visibility stateishidden.

TherequestFullscreen(options)method steps are:

LetpendingDocbethis’snode document.
Letpromisebe a new promise.
IfpendingDocis notfully active,then rejectpromisewith aTypeErrorexception and returnpromise.
Leterrorbe false.
If any of the following conditions are false, then seterrorto true:
- This’snamespaceis theHTML namespaceorthisis anSVGsvgorMathMLmathelement.[SVG][MATHML]
- Thisis not adialogelement.
- Thefullscreen element ready checkforthisreturns true.
- Fullscreen is supported.
- This’srelevant global objecthastransient activationor the algorithm istriggered by a user generated orientation change.
Iferroris false, thenconsume user activationgivenpendingDoc’srelevant global object.
Returnpromise,and run the remaining stepsin parallel.

Iferroris false, then resizependingDoc’snode navigable’stop-level traversable’sactive document’s viewport’s dimensions, optionally taking into accountoptions[ "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 seterrorto true:
- This’snode documentispendingDoc.
- Thefullscreen element ready checkforthisreturns true.
Iferroris true:
1. Append(fullscreenerror,this) topendingDoc’slist of pending fullscreen events.
2. Rejectpromisewith aTypeErrorexception and terminate these steps.
LetfullscreenElementsbe anordered setinitially consisting ofthis.
While true:
1. Letlastbe the lastitemoffullscreenElements.
2. Letcontainerbelast’snode navigable’scontainer.
3. Ifcontaineris null, thenbreak.
4. AppendcontainertofullscreenElements.
For eachelementinfullscreenElements:
1. Letdocbeelement’snode document.
2. Ifelementisdoc’sfullscreen element,continue.
  
  No need to notify observers when nothing has changed.
3. Ifelementisthisandthisis aniframeelement,then setelement’siframe fullscreen flag.
4. Fullscreenelementwithindoc.
5. Append(fullscreenchange,element) todoc’slist of pending fullscreen events.
The order in which elements arefullscreenedis not observable, becauserun the fullscreen stepsis invoked intree order.
Resolvepromisewith undefined.

Implementations with out-of-processnavigablesare left as an exercise to the reader. Input welcome on potential improvements.

ThefullscreenEnabledgetter steps are to return true ifthisisallowed to usethe "fullscreen"feature andfullscreen is supported,and false otherwise.

Thefullscreengetter steps are to return false ifthis’sfullscreen elementis null, and true otherwise.

Use thefullscreenElementattribute instead.

ThefullscreenElementgetter steps are:

Ifthisis ashadow rootand itshostis notconnected,then return null.
Letcandidatebe the result ofretargeting fullscreen elementagainstthis.
Ifcandidateandthisare in the sametree,then returncandidate.
Return null.

Adocumentis said to be asimple fullscreen documentif there is exactly oneelementin itstop layerthat has itsfullscreen flagset.

Adocumentwith twoelementsin itstop layercan be asimple fullscreen document.For example, in addition to thefullscreen elementthere could be an opendialogelement.

Tocollect documents to unfullscreengivendoc,run these steps:

Letdocsbe anordered setconsisting ofdoc.
Whiletrue:
1. LetlastDocbedocs’s lastdocument.
2. Assert:lastDoc’sfullscreen elementis not null.
3. IflastDocis not asimple fullscreen document,break.
4. LetcontainerbelastDoc’snode navigable’scontainer.
5. Ifcontaineris null, thenbreak.
6. Ifcontainer’siframe fullscreen flagis set,break.
7. Appendcontainer’snode documenttodocs.
Returndocs.

This is the set of documents for which thefullscreen elementwill beunfullscreened,but the last document indocsmight have more than oneelementin itstop layerwith thefullscreen flagset, in which case that document will still remain in fullscreen.

Toexit fullscreenadocumentdoc,run these steps:

Letpromisebe a new promise.
Ifdocis notfully activeordoc’sfullscreen elementis null, then rejectpromisewith aTypeErrorexception and returnpromise.
Letresizebe false.
Letdocsbe the result ofcollecting documents to unfullscreengivendoc.
LettopLevelDocbedoc’snode navigable’stop-level traversable’sactive document.
IftopLevelDocis indocs,and it is asimple fullscreen document,then setdoctotopLevelDocandresizeto true.
Ifdoc’sfullscreen elementis notconnected:
1. Append(fullscreenchange,doc’sfullscreen element) todoc’slist of pending fullscreen events.
Returnpromise,and run the remaining stepsin parallel.
Run thefully unlock the screen orientation stepswithdoc.
Ifresizeis true, resizedoc’s viewport to its "normal" dimensions.
Ifdoc’sfullscreen elementis null, then resolvepromisewith undefined and terminate these steps.
LetexitDocsbe the result ofcollecting documents to unfullscreengivendoc.
LetdescendantDocsbe anordered setconsisting ofdoc’sdescendant navigables'active documentswhosefullscreen elementis non-null, if any, intree order.
For eachexitDocinexitDocs:
1. Append(fullscreenchange,exitDoc’sfullscreen element) toexitDoc’slist of pending fullscreen events.
2. Ifresizeis true,unfullscreenexitDoc.
3. Otherwise,unfullscreenexitDoc’sfullscreen element.
For eachdescendantDocindescendantDocs:
1. Append(fullscreenchange,descendantDoc’sfullscreen element) todescendantDoc’slist of pending fullscreen events.
2. UnfullscreendescendantDoc.
The order in which documents areunfullscreenedis not observable, becauserun the fullscreen stepsis invoked intree order.
Resolvepromisewith undefined.

TheexitFullscreen()method steps are to return the result of runningexit fullscreenonthis.

The following are theevent handlers(and their correspondingevent handler event types) that must be supported byElementandDocumentobjects asevent handler IDL attributes:

event handler	event handler event type
`onfullscreenchange`	`fullscreenchange`
`onfullscreenerror`	`fullscreenerror`

These are not supported byShadowRootorWindowobjects, and there are no correspondingevent handler content attributesforElementobjects in any namespace.

4.UI

User agents are encouraged to implement native media fullscreen controls in terms ofrequestFullscreen()andexitFullscreen().

If the end user instructs the user agent to end a fullscreen session initiated viarequestFullscreen(),fully exit fullscreengiven thetop-level traversable’sactive document.

The user agent may end any fullscreen session without instruction from the end user or call toexitFullscreen()whenever the user agent deems it necessary.

5.Rendering

This section is to be interpreted equivalently to the Rendering section of HTML.[HTML]

5.1.`:fullscreen`pseudo-class

The:fullscreenpseudo-class must match anyelementelementfor which one of the following conditions is true:

element’sfullscreen flagis set.
elementis ashadow hostand the result ofretargetingitsnode document’sfullscreen elementagainstelementiselement.

This makes it different from thefullscreenElementAPI, which returns the topmostfullscreen element.

5.2.User-agent level style sheet defaults

@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;
}

6.Permissions Policy Integration

This specification defines apolicy-controlled featureidentified by the string "fullscreen".Itsdefault allowlistis'self'.

Adocument’spermissions policydetermines whether any content in that document is allowed to go fullscreen. If disabled in any document, no content in the document will beallowed to usefullscreen.

Theallowfullscreenattribute of the HTMLiframeelement affects thecontainer policyfor any document nested in that iframe. Unless overridden by theallowattribute, settingallowfullscreenon an iframe is equivalent to<iframe allow= "fullscreen *" >,as described inPermissions Policy§ 6.3.1 allowfullscreen.

7.Security and Privacy Considerations

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 ofrequestFullscreen().

To enable content in achild navigableto go fullscreen, it needs to be specifically allowed via permissions policy, either through theallowfullscreenattribute of the HTMLiframeelement, or an appropriate declaration in theallowattribute of the HTMLiframeelement, or through a `Permissions-Policy` HTTP header delivered with thedocumentthrough which it is nested.

This prevents e.g. content from third parties to go fullscreen without explicit permission.

Previously-hosted definitions

This specification previously hosted the definitions of::backdropand the concept of the document’stop layer.

Acknowledgments

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 byPhilip Jägenstedt(Google,[email protected]). It was originally written byAnne van Kesteren(Apple,[email protected]).Tantek Çelik(Mozilla,[email protected]) sorted out legal hassles.

Intellectual property rights

Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under aCreative Commons Attribution 4.0 International License.To the extent portions of it are incorporated into source code, such portions in the source code are licensed under theBSD 3-Clause Licenseinstead.

This is the Living Standard. Those interested in the patent-review version should view theLiving Standard Review Draft.

Fullscreen API

Abstract

1.Terminology

2.Model

3.API

4.UI

5.Rendering

5.1.`:fullscreen`pseudo-class

5.2.User-agent level style sheet defaults

6.Permissions Policy Integration

7.Security and Privacy Considerations

Previously-hosted definitions

Acknowledgments

Intellectual property rights

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

IDL Index

Fullscreen API

Abstract

1.Terminology

2.Model

3.API

4.UI

5.Rendering

5.1.:fullscreenpseudo-class

5.2.User-agent level style sheet defaults

6.Permissions Policy Integration

7.Security and Privacy Considerations

Previously-hosted definitions

Acknowledgments

Intellectual property rights

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

IDL Index

5.1.`:fullscreen`pseudo-class