If you don’t like change, perhaps web development isn’t for you. I previously described the Full-Screen APIin late 2012 and, while I claimed the implementation details were subject to revision, I didn’t think I’d need a rewrite a year later! This may not be the last, but many thanks to David Storey for highlighting the recent technical transitions…
What is the Full-Screen API?
The API allows a single element to be viewed full-screen. Unlike pressing F11 to force your browser to full-screen, the API is intended for images, videos and games running within a container. When you enter full-screen mode, a message informs the user they can press ESC at any time to return to the page.
The Full-Screen API is now supported by all recent desktop browsers, including IE11. There’s little support on mobile, but those browsers normally run in an almost full-screen view. Unfortunately, we have subtle differences, prefixing requirements, and cross-browser inconsistencies to solve…
The JavaScript API
Assume we have an image with the ID myimage
, which we want to view full-screen. The main methods and properties are:
document.fullscreenEnabled (changed)
This property returns true
when the document is in a state which allows full-screen mode. It can also be used to determine browser support:
if (document.fullscreenEnabled) { ... }
Earlier implementations had an uppercase ‘S’ in ‘Screen’, and it is still required for Firefox. Adding prefixes results in considerably longer cross-browser code:
// full-screen available?
if (
document.fullscreenEnabled ||
document.webkitFullscreenEnabled ||
document.mozFullScreenEnabled ||
document.msFullscreenEnabled
) {
...
}
Opera 12 is the only browser not to require prefixes but Opera 15+ uses webkit
.
element.requestFullscreen() (changed)
This method makes an individual element full-screen, e.g.
document.getElementById("myimage").requestFullscreen();
Again, ‘screen’ has switched to lowercase. The cross-browser code:
var i = document.getElementById("myimage");
// go full-screen
if (i.requestFullscreen) {
i.requestFullscreen();
} else if (i.webkitRequestFullscreen) {
i.webkitRequestFullscreen();
} else if (i.mozRequestFullScreen) {
i.mozRequestFullScreen();
} else if (i.msRequestFullscreen) {
i.msRequestFullscreen();
}
document.fullscreenElement (changed)
This property returns the current element which is being displayed full-screen or null
when not full-screen:
if (document.fullscreenElement) { ... }
‘screen’ is now lowercase. The cross-browser code:
// are we full-screen?
if (
document.fullscreenElement ||
document.webkitFullscreenElement ||
document.mozFullScreenElement ||
document.msFullscreenElement
) {
...
}
document.exitFullscreen (changed)
This method cancels full-screen mode:
document.exitFullscreen;
Again, we have a lowercase ‘screen’. It was previously named cancelFullScreen
, and still is within Firefox. The cross-browser code:
// exit full-screen
if (document.exitFullscreen) {
document.exitFullscreen();
} else if (document.webkitExitFullscreen) {
document.webkitExitFullscreen();
} else if (document.mozCancelFullScreen) {
document.mozCancelFullScreen();
} else if (document.msExitFullscreen) {
document.msExitFullscreen();
}
document.fullscreenchange event
This event is fired when moving to and from full-screen view. No information is provided by the event but you can determine whether full-screen is enabled by checking whether document.fullscreenElement
is not null
.
document.addEventListener("fullscreenchange", function() { ... });
The name has not changed, but we require cross-browser prefixes and camel-casing for IE:
document.addEventListener("fullscreenchange", FShandler);
document.addEventListener("webkitfullscreenchange", FShandler);
document.addEventListener("mozfullscreenchange", FShandler);
document.addEventListener("MSFullscreenChange", FShandler);
document.fullscreenerror event
Full-screen can fail. For example, iframes without an allowfullscreen
attribute or windowed plug-in content may be blocked. A fullscreenerror
event may therefore be fired:
document.addEventListener("fullscreenerror", function() { ... });
The name has not changed, but we require cross-browser prefixes and camel-casing for IE:
document.addEventListener("fullscreenerror", FSerrorhandler);
document.addEventListener("webkitfullscreenerror", FSerrorhandler);
document.addEventListener("mozfullscreenerror", FSerrorhandler);
document.addEventListener("MSFullscreenError", FSerrorhandler);
Full-Screen CSS
We can also influence full-screen styles in CSS…
:fullscreen pseudo class (changed)
You can apply styles to an element or its children when viewed in full-screen mode:
:fullscreen {
...
}
This was previously named :full-screen
, and still is in Webkit and Firefox. For cross-browser code:
:-webkit-full-screen {
}
:-moz-full-screen {
}
:-ms-fullscreen {
}
:fullscreen {
}
::backdrop (new)
You can apply a color or image backdrop when an element with a different aspect-ratio is viewed full-screen :
:fullscreen::backdrop {
background-color: #006; /* dark blue */
}
The backdrop is a pseudo element behind the fullscreen element but above all other page content. It is supported in IE11, but not Firefox and Opera 12. Chrome, Safari, and Opera 15+ include the backdrop element but do not permit it to be styled. For the moment, you can only target IE11, e.g.
:-ms-fullscreen::-ms-backdrop {
background-color: #006; /* dark blue */
}
Styling Differences
In IE11, Firefox, and Opera 12 the full-screen element is set to 100% width and height. Images are therefore stretched and the aspect ratio is ignored. Setting a width and height in IE11 positions a full-screen element to the top-left with a dark backdrop (configurable with ::backdrop). Opera 12 is similar to IE11 but shows a transparent backdrop. Firefox ignores the dimensions. In Chrome, Safari, and Opera 15+ the element is centered with a black backdrop.
If you want some consistency, it’s easy to make the Webkit/Blink browsers stretch like Firefox/IE11:
:-webkit-full-screen {
position: fixed;
width: 100%;
top: 0;
background: none;
}
Alternatively, you can make IE11 follow the Webkit/Blink centering:
:-ms-fullscreen {
width: auto;
height: auto;
margin: auto;
}
This method won’t work in Firefox, which ignores the width and height as mentioned above. To fix it, you’ll need to make the parent element full-screen and apply appropriate sizing as shown in this demonstration.