How to Use the HTML5 Full-Screen API

Update: This article is now outdated. Please see the updated version, How to Use the HTML5 Full-Screen API (Again).

Flash has offered a full-screen mode for many years but, until now, browser vendors have resisted the feature. The main reason: security. If you can force an app to run full-screen, the user loses their browser, taskbar and standard operating system controls. They may not be able to close the window or, worse, nefarious developers could emulate the OS and trick users into handing over passwords, credit card details, etc.

At the time of writing, the HTML5 full-screen API has been implemented in Firefox, Chrome and Safari. Mozilla provide good cross-browser details but it’s worth noting that the specifications and implementation details are likely to change.

Unlike pressing F11 to make your browser go full-screen, the API sets a single element full-screen. It’s intended for images, videos and games using the canvas element. Once an element goes full-screen, a message appears temporarily to inform the user that they can press ESC at any time to return to windowed mode.

The main properties, methods and styles are:

element.requestFullScreen()
Makes an individual element full-screen, e.g. document.getElementById(“myvideo”).requestFullScreen().

document.cancelFullScreen()
Exits full-screen mode and returns to the document view.

document.fullScreen
Returns true if the browser is in full-screen mode.

:full-screen
A CSS pseudo-class which applies to an element when it’s in full-screen mode.

Vexing Vendor Prefixes

Don’t bother trying to use these API names. You’ll require vendor prefixes for BOTH the CSS and JavaScript properties:

Standard	Chrome/Safari	Firefox
.requestFullScreen()	.webkitRequestFullScreen()	.mozRequestFullScreen()
.cancelFullScreen()	.webkitCancelFullScreen()	.mozCancelFullScreen()
.fullScreen	.webkitIsFullScreen	.mozfullScreen
:full-screen	:-webkit-full-screen	:-moz-full-screen

There’s no support in Internet Explorer or Opera yet, but I would suggest you use the ‘ms’ and ‘o’ prefixes for future proofing.

I’ve developed a function in the demonstration page which handles the prefix shenanigans for you:

var pfx = ["webkit", "moz", "ms", "o", ""];
function RunPrefixMethod(obj, method) {
	
	var p = 0, m, t;
	while (p < pfx.length && !obj[m]) {
		m = method;
		if (pfx[p] == "") {
			m = m.substr(0,1).toLowerCase() + m.substr(1);
		}
		m = pfx[p] + m;
		t = typeof obj[m];
		if (t != "undefined") {
			pfx = [pfx[p]];
			return (t == "function" ? obj[m]() : obj[m]);
		}
		p++;
	}

}

We can then make any element viewable full screen by attaching a handler function which determines whether it’s in full-screen mode already and acts accordingly:

var e = document.getElementById("fullscreen");

e.onclick = function() {

	if (RunPrefixMethod(document, "FullScreen") || RunPrefixMethod(document, "IsFullScreen")) {
		RunPrefixMethod(document, "CancelFullScreen");
	}
	else {
		RunPrefixMethod(e, "RequestFullScreen");
	}

}

The CSS

Once the browser enters full-screen mode you’ll almost certainly want to modify the styles for the element and it’s children. For example, if your element normally has a width of 500px, you’ll want to change that to 100% so it uses the space available, e.g.

#myelement
{
	width: 500px;
}

#myelement:full-screen
{
	width: 100%;
}

#myelement:full-screen img
{
	width: 100%;
}

However, you cannot use a list of vendor prefixed selectors:

/* THIS DOES NOT WORK */
#myelement:-webkit-full-screen,
#myelement:-moz-full-screen,
#myelement:-ms-full-screen,
#myelement:-o-full-screen,
#myelement:full-screen
{
	width: 100%;
}

For some bizarre reason, you must repeat the styles in their own blocks or they won’t be applied:

/* this works */
#myelement:-webkit-full-screen	{ width: 100% }
#myelement:-moz-full-screen		{ width: 100% }
#myelement:-ms-full-screen		{ width: 100% }
#myelement:-o-full-screen		{ width: 100% }
#myelement:full-screen			{ width: 100% }

Weird.

View the demonstration page in Firefox, Chrome or Safari…

The technique works well. The only issue I’ve discovered concerns Safari on a two-monitor desktop — it insists on using the first monitor for full-screen mode even if the browser is running on the second screen?

While it’s possibly a little early to use full-screen mode, games developers and video producers should keep an eye on progress.

If you enjoyed reading this post, you’ll love Learnable; the place to learn fresh skills and techniques from the masters. Members get instant access to all of SitePoint’s ebooks and interactive online courses, like HTML5 & CSS3 For the Real World.

Comments on this article are closed. Have a question about HTML5? Why not ask it on our forums?