How to use the Fullscreen API

Bundled with HTML5 came a large number of API goodness and one of the best was the Fullscreen API that provides a native way for the browser to do what was only possible in flash for a long time: display the webpage in fullscreen mode for the user.

This comes in handy if you are displaying video, or images, or if you are developing a game. In fact, any content that needs to be focussed on can benefit from the Fullscreen API.

And best of all, the Fullscreen API is really easy to use…

The methods

A number of methods are part of the Fullscreen API:

element.requestFullScreen()

This method allows a single element to go fullscreen.

Document.getElementById(“myCanvas”).requestFullScreen()

This will cause the canvas with the ID ‘myCanvas’ to go fullscreen.

document.cancelFullScreen()

This simply exits fullscreen mode and returns to the document view.

Document.fullScreen

This will return true if the user is in full-screen mode.

document.fullScreenElement

Returns the element that is currently in full-screen mode.

Note that these are the standard methods but for the time being you will need vendor prefixes in order to make this work in Chrome, Firefox and Safari (Internet Explorer and Opera do not support this API at present).

Launching fullscreen mode 

Since first we need to find out which method the browser recognizes we will create a function that will find the right method for the browser and the call it:

//helper function
function fullScreen(element) {
  if(element.requestFullScreen) {
    element.requestFullScreen();
  } else if(element.webkitRequestFullScreen ) {
    element.webkitRequestFullScreen();
  } else if(element.mozRequestFullScreen) {
    element.mozRequestFullScreen();
  }
}

As you can see all this function does is see if any of the requestFullScreen methods return true and then it calls the function for the correct browser using its vendor prefix.

After this all we need to do is call the fullScreen function like so: 

//for the whole page
var html = document.documentElement;
fullScreen(html);

 // For a specific element on the page
var canvas = document.getElementById('mycanvas');
fullScreen(canvas);

This will send a prompt to the user requesting permission to go fullscreen, if it’s accepted all the toolbars in the browser will vanish and the only thing on the screen will be the desired web page or the single element.

Cancelling fullscreen mode

This method also requires vendor prefixes, so we will use the same idea as above and create a function that will determine which prefix we should be using according to the user’s browser.

One thing you will notice is that this method doesn’t need any elements passed because unlike the requestFullScreen method it always applies to the whole document.

// the helper function
function fullScreenCancel() {
  if(document.requestFullScreen) {
    document.requestFullScreen();
  } else if(document .webkitRequestFullScreen ) {
    document.webkitRequestFullScreen();
  } else if(document .mozRequestFullScreen) {
    document.mozRequestFullScreen();
  }
}

//cancel full-screen
fullScreenCancel();

The CSS pseudo-class

Bundled with this JavaScript API came a CSS pseudo-class called :full-screen and this can be used to style any elements in the webpage when it’s in full-screen mode, this can come in handy because the browser size increases a little when in full-screen mode.

/* Changing something in the body */
:-webkit-full-screen {
  font-size: 16px;
}
:-moz-full-screen {
  font-size: 16px;
}

/*Only one element*/
:-webkit-full-screen img {
  width: 100%;
  height: 100%;
}
:-moz-full-screen img {
  width: 100%;
  height: 100%;
}

Be aware that you can’t separate the vendor prefixes with commas because the browser will not read them:

/* This will not work */
:-webkit-full-screen img,:-moz-full-screen img {
  width: 100%;
  height: 100%;
}

In order for the styles to be applied properly you must place every vendor prefix in it’s own block.

Conclusion

This JavaScript API is one of the least known that shipped with HTML5 but in my opinion it’s both effective and simple to implement. The improved user experience of focussing on a single element, especially for video, images and games is well worth the few lines of code involved.