Fullscreen API

As we move toward more true web applications, our JavaScript APIs are doing their best to keep up.  One very simple but useful new JavaScript API is the Fullscreen API.  The Fullscreen API provides a programmatic way to request fullscreen display from the user, and cancel fullscreen when desired.  Here's how to use this incredibly simple API!

Launching Fullscreen Mode

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

// Find the right method, call on correct element
function launchFullScreen(element) {
  if(element.requestFullScreen) {
    element.requestFullScreen();
  } else if(element.mozRequestFullScreen) {
    element.mozRequestFullScreen();
  } else if(element.webkitRequestFullScreen) {
    element.webkitRequestFullScreen();
  }
}

// Launch fullscreen for browsers that support it!
launchFullScreen(document.documentElement); // the whole page
launchFullScreen(document.getElementById("videoElement")); // any individual element

Simply call the request method on the element you'd like to receive fullscreen and the window morphs to fullscreen, requesting that the user allow fullscreen mode.  Remember it's plausible that the user will reject fullscreen mode.  If fullscreen mode is accepted, the toolbars and general chrome go away, making the document frame span the entire width and height of the screen.

Canceling Fullscreen Mode

The cancelFullScreen method (also prefixed in older browsers) morphs the browser chrome back into standard layout:

// Whack fullscreen
function cancelFullscreen() {
  if(document.cancelFullScreen) {
    document.cancelFullScreen();
  } else if(document.mozCancelFullScreen) {
    document.mozCancelFullScreen();
  } else if(document.webkitCancelFullScreen) {
    document.webkitCancelFullScreen();
  }
}

// Cancel fullscreen for browsers that support it!
cancelFullscreen();

Note that cancelFullScreen is called on the document object only -- not needing to pass the individual element itself.

Fullscreen Properties & Events

Unfortunately the events and properties are still prefixed, but will be unprefixed over time.

• document.fullScreenElement: the element which has been pushed to fullscreen.
• document.fullScreenEnabled:  notes if fullscreen is current enabled.

The fullscreenchange event lets us know when we go to/from fullscreen mode:

var fullscreenElement = document.fullscreenElement || document.mozFullScreenElement || document.webkitFullscreenElement;
var fullscreenEnabled = document.fullscreenEnabled || document.mozFullScreenEnabled || document.webkitFullscreenEnabled;

You can detect which browser-prefixed event to use along with the initial fullscreen method detection.

Fullscreen CSS

Browsers do provide us one helpful bit of fullscreen CSS control:

/* html */
:-webkit-full-screen {
  background: pink;
}
:-moz-full-screen {
  background: pink;
}

/* deeper elements */
:-webkit-full-screen video {
  width: 100%;
  height: 100%;
}

In some cases, WebKit needs a bit of help, so the code above should be kept handy if you're dealing with media.

The fullscreen API is super simple and super useful.  I first saw this API used with MDN's BananaBread demo, an all-client-side first person shooter, a perfect excuse to go fullscreen.  The fullscreen API provides a way to enter and exit fullscreen mode, as well as an event to detect fullscreen state change, so all bases are covered.  Keep this nice API in mind for your future ventures -- it may come in handy!