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
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 :
-
Let hideUntil be the result of running topmost popover ancestor given element , null, and false.
-
If hideUntil is null, then set hideUntil to element ’s node document .
-
Run hide all popovers until given hideUntil , false, and true.
-
Set element ’s fullscreen flag .
-
Remove from the top layer immediately given element .
- Add to the top layer 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
bubbles
andcomposed
attributes set to true, at target .
-
These steps integrate with the event loop defined in HTML. [HTML]
3. API
enum {
FullscreenNavigationUI "auto" ,"show" ,"hide" };dictionary {
FullscreenOptions FullscreenNavigationUI = "auto"; };
navigationUI 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 ; // historicalPromise <undefined >exitFullscreen ();attribute EventHandler onfullscreenchange ;attribute EventHandler onfullscreenerror ; };partial interface mixin DocumentOrShadowRoot { [LegacyLenientSetter ]readonly attribute Element ?fullscreenElement ; };
-
promise = element . requestFullscreen([ options ])
-
Displays
element
fullscreen
and
resolves
promise
when
done.
When supplied, options ’s
navigationUI
member 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 if document has the ability to display elements fullscreen and fullscreen is supported , or false otherwise.
-
promise = document .
exitFullscreen()
-
Stops document ’s fullscreen element from being displayed fullscreen and resolves promise when done.
-
document .
fullscreenElement
-
Returns document ’s fullscreen element .
-
shadowroot .
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 .
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 MathMLmath
element. [SVG] [MATHML] -
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 ["
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
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 . -
Unfullscreen doc ’s fullscreen element .
-
-
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.
4. UI
User
agents
are
encouraged
to
implement
native
media
fullscreen
controls
in
terms
of
requestFullscreen()
and
exitFullscreen()
.
If
the
end
user
instructs
the
user
agent
to
end
a
fullscreen
session
initiated
via
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
exitFullscreen()
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
: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
fullscreenElement
API,
which
returns
the
topmost
fullscreen
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
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
allowfullscreen
attribute
of
the
HTML
iframe
element
affects
the
container
policy
for
any
document
nested
in
that
iframe.
Unless
overridden
by
the
allow
attribute,
setting
allowfullscreen
on
an
iframe
is
equivalent
to
<iframe
allow="fullscreen
*">
,
as
described
in
Permissions
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
of
requestFullscreen()
.
To
enable
content
in
a
child
navigable
to
go
fullscreen,
it
needs
to
be
specifically
allowed
via
permissions
policy,
either
through
the
allowfullscreen
attribute
of
the
HTML
iframe
element,
or
an
appropriate
declaration
in
the
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.
Previously-hosted definitions
This specification previously hosted the definitions of ::backdrop and the concept of the document’s top 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 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.
Intellectual property rights
Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative 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 the BSD 3-Clause License instead.
This is the Living Standard. Those interested in the patent-review version should view the Living Standard Review Draft .