How to Use the HTML5 Full-Screen API (Again)

If you don’t like change, perhaps web development isn’t for you. I previously described the Full-Screen API in 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.

Ready for Deployment?

The HTML5 Full-Screen API is relatively simple but browser differences result in ugly code, and there’s no guarantee it won’t change again. The situation will improve so it may be preferable to invest time and effort in other features until the API becomes more stable. That said, full-screen can be essential for HTML5 games and video-heavy websites. If you don’t want to maintain code yourself, consider using a library such as screenfull.js which smooths over the cracks. Best of luck!

Frequently Asked Questions (FAQs) about HTML5 Full-Screen API