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…

Key Takeaways

• The HTML5 Full-Screen API allows a single element to be viewed full-screen, intended for images, videos, and games running within a container. It’s now supported by all recent desktop browsers, but has limited mobile support.
• The Full-Screen API has methods and properties like document.fullscreenEnabled, element.requestFullscreen(), document.fullscreenElement, and document.exitFullscreen. However, there are subtle differences, prefixing requirements, and cross-browser inconsistencies that need to be addressed for smooth functioning.
• The HTML5 Full-Screen API is relatively simple but browser differences result in complex code, and there’s no guarantee it won’t change again. For HTML5 games and video-heavy websites, full-screen can be essential. If you don’t want to maintain code yourself, consider using a library such as screenfull.js which smooths over the cracks.

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

How can I use the HTML5 Full-Screen API in different browsers?

The HTML5 Full-Screen API is supported by most modern browsers, but the method of implementation may vary. For instance, in Firefox and Chrome, you can use the requestFullscreen method on any HTML element to make it full screen. However, in Internet Explorer, you need to use the msRequestFullscreen method. It’s important to note that these methods can only be triggered by a user action, such as a mouse click or key press, to prevent abuse.

Why is my request for full-screen change being rejected in Firefox?

Firefox has a security feature that only allows full-screen mode to be activated by a user action. If your full-screen request is being rejected, it’s likely because it’s not being triggered by a user action. To resolve this, ensure your full-screen request is tied to a user action like a mouse click or key press.

Can I use the Fullscreen API with Unity?

Yes, you can use the Fullscreen API with Unity. However, there may be some compatibility issues depending on the version of Unity you’re using. If you encounter any issues, it’s recommended to check the Unity forums or GitHub for solutions.

How can I exit full-screen mode using the Fullscreen API?

You can exit full-screen mode by calling the exitFullscreen method on the document object. This will return the browser to its normal state. Like the requestFullscreen method, this can only be triggered by a user action.

Are there any limitations to the Fullscreen API?

The Fullscreen API does have some limitations. For instance, it can only be triggered by a user action to prevent abuse. Additionally, not all elements can be displayed in full-screen mode. Some elements, like the video element, have specific requirements that must be met before they can be displayed in full-screen mode.

How can I detect if the browser is in full-screen mode?

You can detect if the browser is in full-screen mode by checking the fullscreenElement property of the document object. If this property is null, the browser is not in full-screen mode. If it’s not null, the browser is in full-screen mode.

Can I use the Fullscreen API on mobile devices?

Yes, the Fullscreen API is supported on most modern mobile browsers. However, the implementation may vary depending on the browser and device. It’s recommended to test your implementation on multiple devices to ensure compatibility.

How can I handle errors when using the Fullscreen API?

You can handle errors by listening for the fullscreenerror event on the document object. This event is fired when a request to enter or exit full-screen mode is denied.

Can I use the Fullscreen API in a cross-origin iframe?

Yes, but the iframe must have the allowfullscreen attribute. Without this attribute, attempts to enter full-screen mode will be denied.

Is the Fullscreen API supported in all browsers?

While the Fullscreen API is supported in most modern browsers, there are some exceptions. For instance, it’s not supported in Opera Mini. It’s always a good idea to check the compatibility of the API with the browsers your audience uses.