Table of contents
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.
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 <video>
, for example), you can present it in full-screen mode by simply calling its requestFullScreen()
method; this method is implemented in Gecko as element.mozRequestFullScreen()
and in WebKit as element.webkitRequestFullScreen()
.
Let's consider this <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.requestFullScreen) { elem.requestFullScreen(); } else if (elem.mozRequestFullScreen) { elem.mozRequestFullScreen(); } else if (elem.webkitRequestFullScreen) { 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 document which contains the full-screen element receives a mozfullscreenchange
event. When full-screen mode is exited, the document again receives a mozfullscreenchange
event. Note that the mozfullscreenchange
event doesn't provide any information itself as to whether the document is entering or exiting full-screen mode, but if the document has a non null mozFullScreenElement
, you know you're in full-screen mode.
When a full-screen request fails
It's not guaranteed that you'll be able to switch into full-screen mode. For example, <iframe>
elements have the
mozallowfullscreen
attribute in order to opt-in to allowing their content 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 which requested full-screen will receive a mozfullscreenerror
event.
Getting out of full screen mode
The user always has the ability to exit full-screen mode of their own accord; see 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 document
provides some additional information that can be useful when developing full-screen web applications:
fullScreen
- The
fullScreen
attribute tells you if the document is currently displaying an element in full-screen mode. fullScreenElement
- The
fullScreenElement
attribute tells you theelement
that's currently being displayed full-screen. If this is non-null, the document is in full-screen mode. If this is null, the document is not in full-screen mode. fullScreenEnabled
- The
fullScreenEnabled
attribute tells you whether or not the document is currently in a state that would allow full-screen mode to be requested.
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.
Example
In this example, a video is presented in a web page. Pressing the Return or Enter key lets the user toggle between windowed and full-screen presentation of the video.
Watching for the Enter key
When the page is loaded, this code is run to set up an event listener to watch for the 'enter' key.
document.addEventListener("keydown", function(e) { if (e.keyCode == 13) { toggleFullScreen(); } }, false);
Toggling full screen mode
This code is called when the user hits the Enter key, as seen above.
function toggleFullScreen() { if ((document.fullScreenElement && document.fullScreenElement !== null) || // alternative standard method (!document.mozFullScreen && !document.webkitIsFullScreen) { // current working methods if (document.documentElement.requestFullScreen) { document.documentElement.requestFullScreen(); } else if (document.documentElement.mozRequestFullScreen) { document.documentElement.mozRequestFullScreen(); } else if (document.documentElement.webkitRequestFullScreen) { document.documentElement.webkitRequestFullScreen(Element.ALLOW_KEYBOARD_INPUT); } } else { if (document.cancelFullScreen) { document.cancelFullScreen(); } else if (document.mozCancelFullScreen) { document.mozCancelFullScreen(); } else if (document.webkitCancelFullScreen) { document.webkitCancelFullScreen(); } } }
This starts by looking at the value of the fullScreen
attribute on the document
(checking it prefixed with both -moz-
and -webkit-
). If it's false
, the document is currently in windowed mode, so we need to switch to full-screen mode. The spec draft has a different fullScreenElement
method to check whether or not an element is in full-screen mode, if it's null
then we are in windowed mode. Both gecko and webkit have implemented a the non-standard fullScreen
method so far. Switching to full-screen mode is done by calling either element.mozRequestFullScreen()
or webkitRequestFullScreen()
, depending on which is available.
If full screen mode is already active, we call document.mozCancelFullScreen()
or webkitCancelFullScreen()
, again depending on which browser is in use.
Browser compatibility
Although both Gecko and WebKit implement a draft of this API, there are some subtle differences. This document doesn't necessarily try to call them all into focus. The article will be revised as the spec and implementations fall closer into alignment with one another.
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | 15 -webkit | 9.0 (9.0) -moz | ? | ? | ? |
fullScreenEnabled | ? | 10.0 (10.0) -moz | ? | ? | ? |
Feature | Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|
Basic support | ? | 9.0 (9.0) -moz | ? | ? | ? |
fullScreenEnabled | ? | 10.0 (10.0) moz | ? | ? | ? |
Gecko notes
Although this API was introduced in Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6)
, it's not enabled by default in that release. To enable it, set the full-screen-api.enabled
preference to true
. The API is enabled by default in Gecko 10.0 (Firefox 10.0 / Thunderbird 10.0)
.
Specification
Non-standard methods
These are some of the methods that browsers implemented before the standard was drafted. Having the standard methods described above it's better to avoid using the following ones:
window.fullScreen
(Firefox)HTMLMediaElement.webkitDisplayingFullscreen
HTMLMediaElement.webkitEnterFullscreen
HTMLMediaElement.webkitExitFullscreen
HTMLMediaElement.webkitSupportsFullscreen