The HTML5 Full-Screen API

The Fullscreen API allows a DOM element (and its descendants) to be represented in full screen. What it allows is to visualize the page by removing any element of the browser (menus, tabs,...). With this we can put from the document itself to full screen, video elements, images,...

Fullscreen API methods

The first thing we need to know is the methods that allow us to handle the Fullscreen API. The methods that allow us to visualize an element in full screen are:

Document.exitFullscreen()

Element.requestFullscreen()

requestFullscreen()

It asks the user agent (which will normally be the browser) to be able to display an element in full screen. The Element.requestFullscreen method will return a promise or Promise that will be solved once the full screen mode is activated.

exitFullscreen()

Requests the user agent to exit the full screen display mode to return to normal display. The Document.exitFullscreen method will return a Promise that will be solved once the full screen mode has been disabled.

How to Launch the Fullscreen Mode

The fullscreen API's requestFullScreen method is still prefixed in some browsers, so we'll need to do a bit ofsearching to find it:

function getFullscreen(element){
if(element.requestFullscreen) {
element.requestFullscreen();
} else if(element.mozRequestFullScreen) {
element.mozRequestFullScreen();
} else if(element.webkitRequestFullscreen) {
element.webkitRequestFullscreen();
} else if(element.msRequestFullscreen) {
element.msRequestFullscreen();
}
}

We see that the first thing we do is check if the element on which we want to put the full screen supports this capability. This information is given by the requestFullscreen property. If it does support it will be sufficient to invoke the requestFullscreen method on the element. In this case we use the hacks of the different browsers.

Now we simply need to call our getFullscreen method by passing it the element that represents the entire document.documentElement.

getFullscreen(document.documentElement);

Full-screen item

Now that we have seen how to put the document in full screen, let's move on to perform the same action with an element. In this case we are going to use a video element to show how we can put an element in full screen. The first thing we'll do is create the video element on our page:

<video id="myvideo" src="video.ogv" controls>
Your browser does not support the element <code>video</code>.
</video>

The next thing we'll do is invoke the getFullscreen method we've defined. But in this case we'll call the video element. To get the video element we'll need to use the getElementById method.

getFullscreen(document.getElementById("myvideo"));

How to Remove Fullscreen Mode

The remove FullScreen method you have to morphs the browser chrome back into standard layout:

function exitFullscreen() {
if(document.exitFullscreen) {
document.exitFullscreen();
} else if(document.mozCancelFullScreen) {
document.mozCancelFullScreen();
} else if(document.webkitExitFullscreen) {
document.webkitExitFullscreen();
}
}

Once we have this method we simply have to invoke it to get out of the full screen.

exitFullscreen();

Fullscreen API properties

To be able to handle the Fullscreen API we have two properties:

1. DocumentOrShadowRoot.fullscreenElement

2. Document.fullscreenEnabled

fullscreenElement

The fullscreenElement property tells us which element of the DOM or the "shadow DOM" is being displayed in full screen.

fullscreenEnabled

Through the property fullscreenEnabled indicates if we can activate the full screen mode, which would return the true value or if the full screen mode is not available. In this second case the value of the property will be false.

How to know if the full screen is active

Playing with the properties fullscreenEnabled and fullscreenElement we can check if we have the user agent being shown in full screen and also we can know which element is the one being shown in full screen.

var fullscreenElement = document.fullscreenElement || document.mozFullScreenElement || document.webkitFullscreenElement;
var fullscreenEnabled = document.fullscreenEnabled || document.mozFullScreenEnabled || document.webkitFullscreenEnabled;
console.log('enabled:' + fullscreenEnabled);
console.log('element:' + fullscreenElement);

In the same way as in the previous cases we have to rely on the hacks that the different browsers have in order to evaluate the content of the properties.

Fullscreen API events

Along with the properties and method of the Fullscreen API we will have the event management. This event management will help us to know when there has been a change to or from the full screen or when an error has occurred in the management of the full screen.

The events we can manage are:

• Document.onfullscreenchange
• Document.onfullscreenerror
• Element.onfullscreenchange
• Element.onfullscreenerror

We can see that the events can be applied to a whole element or to the whole document. All depending on what we are managing the whole screen.

onfullscreenchange

An event is sent either to a document (or Document) or to an element (Element), depending on what we are trying to show full screen, either a specific element or the whole page or document.

onfullscreenerror

An error event is sent to the document or item that attempted to display in full screen or exit it.

Controlling the switch to full screen

We have already seen how we can help the user to put a document or elements to full screen. But, what happens if it is the user himself who puts the user agent to full screen? How can we take advantage of knowing that he is visualizing the content in that way?

In this case what we have to do is to control the onfullscreenchange event. To do this we will register a listener that controls it.

document.addEventListener("fullscreenchange",changeScreen,false);
document.addEventListener("webkitfullscreenchange",changeScreen,false);
document.addEventListener("mozfullscreenchange",changeScreen,false);
document.addEventListener("MSFullscreenchange",changeScreen,false);

We have put all the hacks of the onfullscreenchange event and sent them to changeScreen  function.

function changeScreen(event){
console.log("Change to full screen " + Date.now());
}

Fullscreen API dictionaries

The Fullscreenc API has a FullscreenOptions dictionary. This dictionary can be sent to the Element.requestFullscreen method to specify additional properties.

Fullscreen API Multi-Browser Support

In this article we have seen how to handle the methods defined by the Fullscreen API standard, although the support may vary by each web browser and that is why we will have to rely on the hack of each browser.

In this way you will have to take into consideration the following:

• .mozRequestFullScreen()
• .webkitRequestFullscreen()
• .msRequestFullscreen();

Silvia Mazzetta

Web Developer, Blogger, Creative Thinker, Social media enthusiast, Italian expat in Spain, mom of little 9 years old geek, founder of  @manoweb. A strong conceptual and creative thinker who has a keen interest in all things relate to the Internet. A technically savvy web developer, who has multiple  years of website design expertise behind her.  She turns conceptual ideas into highly creative visual digital products.