Build 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 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.fullscreenElementis 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.