Using fullscreen mode

  • Revision slug: DOM/Using_full-screen_mode
  • Revision title: Using full-screen mode
  • Revision id: 31129
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment more deets; 998 words added

Revision Content

{{ SeeCompatTable() }}

The full-screen API provides an easy way for web content to be presented using the user's entire screen. This article provides information about using this API.

Note: This API is early in the standardization process. Although both Gecko and Google Chrome have implementations, they are not currently mutually-compatible, and neither implements the current draft of the specification. For that reason, at least in Firefox, it isn't enabled by default at this time. Because the specification is currently an extremely early draft, this documentation is subject to be entirely wrong, and is very preliminary. Once the specification has settled down a bit, we will clean up the documentation to be more browser-agnostic.

The API lets you easily direct the browser to make an element and its children, if any, occupy the full screen, eliminating all browser user interface and other applications from the screen for the duration.

Activating full-screen mode

Given an element that you'd like to present in full-screen mode (such as a {{ HTMLElement("video") }}, for example), you can present it in full-screen mode by simply calling its requestFullScreen() method; this method is implemented in Gecko as {{ domxref("element.mozRequestFullScreen()") }} and in WebKit as element.webkitRequestFullScreen().

Let's consider this {{ HTMLElement("video") }} element:

<video controls id="myvideo">
  <source src="somevideo.webm"></source>
  <source src="somevideo.mp4"></source>
</video>

We can put that video into full-screen mode with script like this:

var elem = document.getElementById("myvideo");
if (elem.mozRequestFullScreen) {
  elem.mozRequestFullScreen();
} else {
  elem.webkitRequestFullScreen();
}

Presentation differences

It's worth noting a key difference here between the Gecko and WebKit implementations at this time: Gecko automatically adds CSS rules to the element to stretch it to fill the screen: "width: 100%; height: 100%". WebKit doesn't do this; instead, it centers the full-screen element at the same size in a screen that's othewise black. To get the same full-screen behavior in WebKit, you need to add your own "width: 100%; height: 100%;" CSS rules to the element yourself:

:-webkit-full-screen #myvideo {
  width: 100%;
  height: 100%;
}

On the other hand, if you're trying to emulate WebKit's behavior on Gecko, you need to place the element you want to present inside another element, which you'll make full-screen instead, and use CSS rules to adjust the inner element to match the appearance you want.

Notification

When full-screen mode is successfully engaged, the element that has been placed into full-screen mode receives a {{ domevent("mozfullscreenchange") }} event. It will receive another one when full-screen mode is terminated. This event doesn't provide any information as to whether the element is entering or exiting full-screen mode. There are a couple of ways you can deal with this.

  • Keep a state flag that you update when the event occurs.
  • Each time the event is fired, change the function that handles the event based on which mode you must be in; that is, start with the event handler as an enterFullScreen() function, and have that function change the event handler for the "mozfullscreenchange" event to an exitFullScreen() function.

When full-screen mode fails

It's not guaranteed that you'll be able to switch into full-screen mode. For example, {{ HTMLElement("iframe") }} elements have the {{ HTMLAttrXRef("mozallowfullscreen", "iframe") }} attribute, which lets them opt-out of allowing themselves to be displayed in full-screen mode. In addition, certain kinds of content, such as windowed plug-ins, cannot be presented in full-screen mode. Attempting to put an element which can't be displayed in full-screen mode (or the parent or descendant of such an element) won't work. Instead, the element will receive a {{domevent("mozfullscreenerror") event.

Getting out of full screen mode

The user always has the ability to exit full-screen mode of their own accord; see {{ anch("Things your users want to know") }}. You can also do so programmatically by calling the cancelFullScreen() method; this is implemented in Gecko as mozCancelFullScreen() and WebKit as webkitCancelFullScreen().

Other information

The {{ domxref("document") }} provides some additional information that can be useful when developing full-screen web applications:

{{ domxref("document.mozFullScreen", "fullScreen") }}
The fullScreen attribute tells you if the document is currently displaying an element in full-screen mode.
{{ domxref("document.mozFullScreenElement", "fullScreenElement") }}
The fullScreenElement attribute tells you the {{ domxref("element") }} that's currently being displayed full-screen.
{{ domxref("document.mozFullScreenEnabled", "fullScreenEnabled") }}
The fullScreenEnabled attribute tells you whether or not the document is currently in a state that would allow full-screen mode to be enabled.

Things your users want to know

You'll want to be sure to let your users know that they can press the ESC key (or F11) to exit full-screen mode.

Also, any alphanumeric keyboard input while in full-screen mode causes a warning message to appear; this is done to help guard against phishing attacks. The following keys are the only ones that don't cause this warning message to appear:

  • left arrow
  • right arrow
  • up arrow
  • down arrow
  • space
  • shift
  • control
  • alt
  • page up
  • page down
  • home
  • end
  • tab
  • meta

In addition, navigating to another page, changing tabs, or switching to another application (using, for example, Alt-Tab) while in full-screen mode exits full-screen mode as well.

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support {{ CompatUnknown() }} {{ CompatGeckoDesktop("9.0") }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support {{ CompatUnknown() }} {{ CompatGeckoMobile("9.0") }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}

Gecko notes

Although this API was introduced in Gecko 9.0 {{ geckoRelease("9.0") }}, it's not enabled by default in that release. To enable it, set the full-screen-api.enabled preference to true.

Specification

Not part of any specification.

Revision Source

<p>{{ SeeCompatTable() }}</p>
<p>The full-screen API provides an easy way for web content to be presented using the user's entire screen. This article provides information about using this API.</p>
<div class="note"><strong>Note:</strong> This API is early in the standardization process. Although both Gecko and Google Chrome have implementations, they are not currently mutually-compatible, and neither implements the current draft of the specification. For that reason, at <a href="/en/DOM/Using_full-screen_mode#Gecko_notes" title="en/DOM/Using_full-screen_mode#Gecko_notes">least in Firefox</a>, it isn't enabled by default at this time. Because the <a class=" external" href="http://dvcs.w3.org/hg/fullscreen/raw-file/tip/Overview.html" title="http://dvcs.w3.org/hg/fullscreen/raw-file/tip/Overview.html">specification</a> is currently an extremely early draft, this documentation is subject to be entirely wrong, and is very preliminary. Once the specification has settled down a bit, we will clean up the documentation to be more browser-agnostic.</div>
<p>The API lets you easily direct the browser to make an element and its children, if any, occupy the full screen, eliminating all browser user interface and other applications from the screen for the duration.</p>
<h2 name="Specification">Activating full-screen mode</h2>
<p>Given an element that you'd like to present in full-screen mode (such as a {{ HTMLElement("video") }}, for example), you can present it in full-screen mode by simply calling its <code>requestFullScreen()</code> method; this method is implemented in Gecko as {{ domxref("element.mozRequestFullScreen()") }} and in WebKit as <code>element.webkitRequestFullScreen()</code>.</p>
<p>Let's consider this {{ HTMLElement("video") }} element:</p>
<pre class="brush: html">&lt;video controls id="myvideo"&gt;
  &lt;source src="somevideo.webm"&gt;&lt;/source&gt;
  &lt;source src="somevideo.mp4"&gt;&lt;/source&gt;
&lt;/video&gt;
</pre>
<p>We can put that video into full-screen mode with script like this:</p>
<pre class="brush: js">var elem = document.getElementById("myvideo");
if (elem.mozRequestFullScreen) {
  elem.mozRequestFullScreen();
} else {
  elem.webkitRequestFullScreen();
}
</pre>
<h3>Presentation differences</h3>
<p>It's worth noting a key difference here between the Gecko and WebKit implementations at this time: Gecko automatically adds CSS rules to the element to stretch it to fill the screen: "<code>width: 100%; height: 100%</code>". WebKit doesn't do this; instead, it centers the full-screen element at the same size in a screen that's othewise black. To get the same full-screen behavior in WebKit, you need to add your own "<code>width: 100%; height: 100%;</code>" CSS rules to the element yourself:</p>
<pre class="brush: css">:-webkit-full-screen #myvideo {
  width: 100%;
  height: 100%;
}
</pre>
<p>On the other hand, if you're trying to emulate WebKit's behavior on Gecko, you need to place the element you want to present inside another element, which you'll make full-screen instead, and use CSS rules to adjust the inner element to match the appearance you want.</p>
<h3>Notification</h3>
<p>When full-screen mode is successfully engaged, the element that has been placed into full-screen mode receives a {{ domevent("mozfullscreenchange") }} event. It will receive another one when full-screen mode is terminated. This event doesn't provide any information as to whether the element is entering or exiting full-screen mode. There are a couple of ways you can deal with this.</p>
<ul> <li>Keep a state flag that you update when the event occurs.</li> <li>Each time the event is fired, change the function that handles the event based on which mode you must be in; that is, start with the event handler as an <code>enterFullScreen()</code> function, and have that function change the event handler for the "mozfullscreenchange" event to an <code>exitFullScreen()</code> function.</li>
</ul>
<h3>When full-screen mode fails</h3>
<p>It's not guaranteed that you'll be able to switch into full-screen mode. For example, {{ HTMLElement("iframe") }} elements have the {{ HTMLAttrXRef("mozallowfullscreen", "iframe") }} attribute, which lets them opt-out of allowing themselves to be displayed in full-screen mode. In addition, certain kinds of content, such as windowed plug-ins, cannot be presented in full-screen mode. Attempting to put an element which can't be displayed in full-screen mode (or the parent or descendant of such an element) won't work. Instead, the element will receive a {{domevent("mozfullscreenerror") event.</p>
<h2>Getting out of full screen mode</h2>
<p>The user always has the ability to exit full-screen mode of their own accord; see {{ anch("Things your users want to know") }}. You can also do so programmatically by calling the <code>cancelFullScreen()</code> method; this is implemented in Gecko as <a href="/en/DOM/document.mozCancelFullScreen" title="document.mozCancelFullScreen"><code>mozCancelFullScreen()</code></a> and WebKit as <code>webkitCancelFullScreen()</code>.</p>
<h2>Other information</h2>
<p>The {{ domxref("document") }} provides some additional information that can be useful when developing full-screen web applications:</p>
<dl> <dt>{{ domxref("document.mozFullScreen", "fullScreen") }}</dt> <dd>The <code>fullScreen</code> attribute tells you if the document is currently displaying an element in full-screen mode.</dd> <dt>{{ domxref("document.mozFullScreenElement", "fullScreenElement") }}</dt> <dd>The <code>fullScreenElement</code> attribute tells you the {{ domxref("element") }} that's currently being displayed full-screen.</dd> <dt>{{ domxref("document.mozFullScreenEnabled", "fullScreenEnabled") }}</dt> <dd>The <code>fullScreenEnabled</code> attribute tells you whether or not the document is currently in a state that would allow full-screen mode to be enabled.</dd>
</dl>
<h2 name="Specification">Things your users want to know</h2>
<p>You'll want to be sure to let your users know that they can press the ESC key (or F11) to exit full-screen mode.</p>
<p>Also, any alphanumeric keyboard input while in full-screen mode causes a warning message to appear; this is done to help guard against phishing attacks. The following keys are the only ones that don't cause this warning message to appear:</p>
<div> <div class="threecolumns" style="undefined"> <ul> <li>left arrow</li> <li>right arrow</li> <li>up arrow</li> <li>down arrow</li> <li>space</li> <li>shift</li> <li>control</li> <li>alt</li> <li>page up</li> <li>page down</li> <li>home</li> <li>end</li> <li>tab</li> <li>meta</li> </ul> </div>
</div>
<p>In addition, navigating to another page, changing tabs, or switching to another application (using, for example, Alt-Tab) while in full-screen mode exits full-screen mode as well.</p>
<h2 name="Specification">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Chrome</th> <th>Firefox (Gecko)</th> <th>Internet Explorer</th> <th>Opera</th> <th>Safari</th> </tr> <tr> <td>Basic support</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatGeckoDesktop("9.0") }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> </tbody> </table>
</div>
<div id="compat-mobile"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Android</th> <th>Firefox Mobile (Gecko)</th> <th>IE Mobile</th> <th>Opera Mobile</th> <th>Safari Mobile</th> </tr> <tr> <td>Basic support</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatGeckoMobile("9.0") }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> </tbody> </table>
</div>
<h3>Gecko notes</h3>
<p>Although this API was introduced in Gecko 9.0 {{ geckoRelease("9.0") }}, it's not enabled by default in that release. To enable it, set the <code>full-screen-api.enabled</code> preference to <code>true</code>.</p>
<h2 name="Specification">Specification</h2>
<p>Not part of any specification.</p>
Revert to this revision