1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
---
title: Fullscreen API
slug: Web/API/Fullscreen_API
translation_of: Web/API/Fullscreen_API
original_slug: DOM/Using_fullscreen_mode
---
<div>{{DefaultAPISidebar("Fullscreen API")}}</div>
<p>The <strong>Fullscreen API</strong> adds methods to present a specific {{DOMxRef("Element")}} (and its descendants) in full-screen mode, and to exit full-screen mode once it is no longer needed. This makes it possible to present desired content—such as an online game—using the user's entire screen, removing all browser user interface elements and other applications from the screen until full-screen mode is shut off.</p>
<p>See the article <a href="/en-US/docs/Web/API/Fullscreen_API/Guide">Guide to the Fullscreen API</a> for details on how to use the API.</p>
<div class="blockIndicator note">
<p><strong>Note:</strong> Support for this API varies somewhat across browsers, with many requiring vendor prefixes and/or not implementing the latest specification. See the {{anch("Browser compatibility")}} section below for details on support for this API. You may wish to consider using a library such as <a href="https://github.com/rafrex/fscreen">Fscreen</a> for vendor agnostic access to the Fullscreen API.</p>
</div>
<h2 id="Interfaces">Interfaces</h2>
<p><em>The Fullscreen API has no interfaces of its own. Instead, it augments several other interfaces to add the methods, properties, and event handlers needed to provide full-screen functionality. These are listed in the following sections.</em></p>
<h2 id="Methods">Methods</h2>
<p>The Fullscreen API adds methods to the {{DOMxRef("Document")}} and {{DOMxRef("Element")}} interfaces to allow turning off and on full-screen mode.</p>
<h3 id="Methods_on_the_Document_interface">Methods on the Document interface</h3>
<dl>
<dt>{{DOMxRef("Document.exitFullscreen()")}}</dt>
<dd>Requests that the {{Glossary("user agent")}} switch from full-screen mode back to windowed mode. Returns a {{jsxref("Promise")}} which is resolved once full-screen mode has been completely shut off.</dd>
</dl>
<h3 id="Methods_on_the_Element_interface">Methods on the Element interface</h3>
<dl>
<dt>{{DOMxRef("Element.requestFullscreen()")}}</dt>
<dd>Asks the user agent to place the specified element (and, by extension, its descendants) into full-screen mode, removing all of the browser's UI elements as well as all other applications from the screen. Returns a {{jsxref("Promise")}} which is resolved once full-screen mode has been activated.</dd>
</dl>
<h2 id="Properties">Properties</h2>
<p><em>The {{DOMxRef("Document")}} interface provides properties that can be used to determine if full-screen mode is supported and available, and if full-screen mode is currently active, which element is using the screen.</em></p>
<dl>
<dt>{{DOMxRef("DocumentOrShadowRoot.fullscreenElement")}}</dt>
<dd>The <code>fullscreenElement</code> property tells you the {{DOMxRef("Element")}} that's currently being displayed in full-screen mode on the DOM (or shadow DOM). If this is <code>null</code>, the document is not in full-screen mode.</dd>
<dt>{{DOMxRef("Document.fullscreenEnabled")}}</dt>
<dd>The <code>fullscreenEnabled</code> property tells you whether or not it is possible to engage full-screen mode. This is <code>false</code> if full-screen mode is not available for any reason (such as the <code>"fullscreen"</code> feature not being allowed, or full-screen mode not being supported).</dd>
</dl>
<h3 id="Event_handlers">Event handlers</h3>
<p><em>The Fullscreen API defines two events which can be used to detect when full-screen mode is turned on and off, as well as when errors occur during the process of changing between full-screen and windowed modes. Event handlers for these events are available on the {{DOMxRef("Document")}} and {{DOMxRef("Element")}} interfaces.</em></p>
<div class="blockIndicator note">
<p><strong>Note:</strong> These event handler properties are <em>not</em> available as HTML content attributes. In other words, you cannot specify event handlers for {{Event("fullscreenchange")}} and {{Event("fullscreenerror")}} in the HTML content. They must be added by JavaScript code.</p>
</div>
<h4 id="Event_handlers_on_documents">Event handlers on documents</h4>
<dl>
<dt>{{DOMxRef("Document.onfullscreenchange")}}</dt>
<dd>An event handler for the {{Event("fullscreenchange")}} event that's sent to a {{DOMxRef("Document")}} when that document is placed into full-screen mode, or when that document exits full-screen mode. This handler is called only when the entire document is presented in full-screen mode.</dd>
<dt>{{DOMxRef("Document.onfullscreenerror")}}</dt>
<dd>An event handler for the {{Event("fullscreenerror")}} event that gets sent to a {{DOMxRef("Document")}} when an error occurs while trying to enable or disable full-screen mode for the entire document.</dd>
</dl>
<h4 id="Event_handlers_on_elements">Event handlers on elements</h4>
<dl>
<dt>{{DOMxRef("Element.onfullscreenchange")}}</dt>
<dd>An event handler which is called when the {{Event("fullscreenchange")}} event is sent to the element, indicating that the element has been placed into, or removed from, full-screen mode.</dd>
<dt>{{DOMxRef("Element.onfullscreenerror")}}</dt>
<dd>An event handler for the {{Event("fullscreenerror")}} event when sent to an element which has encountered an error while transitioning into or out of full-screen mode.</dd>
</dl>
<h3 id="Obsolete_properties">Obsolete properties</h3>
<dl>
<dt>{{DOMxRef("Document.fullscreen")}} {{Deprecated_Inline}}</dt>
<dd>A Boolean value which is <code>true</code> if the document has an element currently being displayed in full-screen mode; otherwise, this returns <code>false</code>.
<div class="note"><strong>Note:</strong> Use the {{DOMxRef("Document.fullscreenElement", "fullscreenElement")}} property on the {{DOMxRef("Document")}} or {{DOMxRef("ShadowRoot")}} instead; if it's not <code>null</code>, then it's an {{DOMxRef("Element")}} currently being displayed in full-screen mode.</div>
</dd>
</dl>
<h2 id="Events" name="Events">Events</h2>
<p><em>The Fullscreen API defines two events which can be used to detect when full-screen mode is turned on and off, as well as when errors occur during the process of changing between full-screen and windowed modes.</em></p>
<dl>
<dt>{{Event("fullscreenchange")}}</dt>
<dd>Sent to a {{DOMxRef("Document")}} or {{DOMxRef("Element")}} when it transitions into or out of full-screen mode.</dd>
<dt>{{Event("fullscreenerror")}}</dt>
<dd>Sent to a <code>Document</code> or <code>Element</code> if an error occurs while attempting to switch it into or out of full-screen mode.</dd>
</dl>
<h2 id="Dictionaries">Dictionaries</h2>
<dl>
<dt>{{DOMxRef("FullscreenOptions")}}</dt>
<dd>Provides optional settings you can specify when calling {{DOMxRef("Element.requestFullscreen", "requestFullscreen()")}}.</dd>
</dl>
<h2 id="Controlling_access">Controlling access</h2>
<p>The availability of full-screen mode can be controlled using <a href="/en-US/docs/Web/HTTP/Feature_Policy">Feature Policy</a>. The full-screen mode feature is identified by the string <code>"fullscreen"</code>, with a default allow-list value of <code>"self"</code>, meaning that full-screen mode is permitted in top-level document contexts, as well as to nested browsing contexts loaded from the same origin as the top-most document.</p>
<p>See <a href="/en-US/docs/Web/HTTP/Feature_Policy/Using_Feature_Policy">Using Feature Policy</a> to learn more about using Feature Policy to control access to an API.</p>
<h2 id="Usage_notes" name="Usage_notes">Usage notes</h2>
<p>Users can choose to exit full-screen mode simply by pressing the <kbd>ESC</kbd> (or <kbd>F11</kbd>) key, rather than waiting for the site or app to programmatically do so. Make sure you provide, somewhere in your user interface, appropriate user interface elements that inform the user that this option is available to them.</p>
<div class="note">
<p><strong>Note:</strong> Navigating to another page, changing tabs, or switching to another application using any application switcher (or <kbd>Alt</kbd>-<kbd>Tab</kbd>) will likewise exit full-screen mode.</p>
</div>
<h2 id="Example">Example</h2>
<p>In this example, a video is presented in a web page. Pressing the <kbd>Return</kbd> or <kbd>Enter</kbd> key lets the user toggle between windowed and full-screen presentation of the video.</p>
<p><a href="/samples/domref/fullscreen.html">View Live Examples</a></p>
<h3 id="Watching_for_the_Enter_key">Watching for the Enter key</h3>
<p>When the page is loaded, this code is run to set up an event listener to watch for the <kbd>Enter</kbd> key.</p>
<pre class="brush: js">document.addEventListener("keypress", function(e) {
if (e.keyCode === 13) {
toggleFullScreen();
}
}, false);
</pre>
<h3 id="Toggling_full-screen_mode">Toggling full-screen mode</h3>
<p>This code is called by the event handler above when the user hits the <kbd>Enter</kbd> key.</p>
<pre class="brush: js">function toggleFullScreen() {
if (!document.fullscreenElement) {
document.documentElement.requestFullscreen();
} else {
if (document.exitFullscreen) {
document.exitFullscreen();
}
}
}</pre>
<p>This starts by looking at the value of the {{DOMxRef("Document", "document")}}'s <code>fullscreenElement</code> attribute. In a real-world deployment, at this time, you'll want to check for prefixed versions of this (<code>mozFullScreenElement</code>, <code>msFullscreenElement</code>, or <code>webkitFullscreenElement</code>, for example). If the value is <code>null</code>, the document is currently in windowed mode, so we need to switch to full-screen mode; otherwise, it's the element that's currently in full-screen mode. Switching to full-screen mode is done by calling {{DOMxRef("Element.requestFullscreen()")}} on the {{HTMLElement("video")}} element.</p>
<p>If full-screen mode is already active (<code>fullscreenElement</code> is not <code>null</code>), we call {{DOMxRef("Document.exitFullscreen", "exitFullscreen()")}} on the <code>document</code> to shut off full-screen mode.</p>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
<thead>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{SpecName("Fullscreen")}}</td>
<td>{{Spec2("Fullscreen")}}</td>
<td>Initial version.</td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility" name="Browser_compatibility">Browser compatibility</h2>
<h3 id="Document.fullscreen"><code>Document.fullscreen</code></h3>
<div>
<p>{{Compat("api.Document.fullscreen")}}</p>
</div>
<h3 id="Document.fullscreenEnabled"><code>Document.fullscreenEnabled</code></h3>
<div>
<p>{{Compat("api.Document.fullscreenEnabled")}}</p>
</div>
<h2 id="See_also">See also</h2>
<ul>
<li><a href="/en-US/docs/Web/API/Fullscreen_API">Using full-screen mode</a></li>
<li>{{DOMxRef("Element.requestFullscreen()")}}</li>
<li>{{DOMxRef("Document.exitFullscreen()")}}</li>
<li>{{DOMxRef("Document.fullscreen")}}</li>
<li>{{DOMxRef("Document.fullscreenElement")}}</li>
<li>{{CSSxRef(":fullscreen")}}, {{CSSxRef("::backdrop")}}</li>
<li>{{HTMLAttrXRef("allowfullscreen", "iframe")}}</li>
</ul>
|
