Fullscreen API

Written by David Walsh on November 5, 2012

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.mozScreenEnabled || document.webkitScreenEnabled;

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!

Comments

  1. I think the fullscreen API could be a great thing, if properly used. For instance, offering a full screen option accompanying an HTML5 video or slideshow element. As long as it’s accompanied by a similar exit fullscreen option that’s also readily available to the user.

    I’m afraid advertisers will use it as a way to automatically put the user into full screen mode with no option to exit.

  2. It works well in OS X. It uses the same full screen application UI as native applications, where you can revert it to being windowed by mousing over the top edge of the screen and clicking the button in the menu bar.

  3. in OSX, Chrome 22.

    document.fullScreenEnabled is: undefined

  4. This is very nice site for learn

  5. Is there any way to detect if full screen is enabled via css? Or are we forced to sniff in Javascript and set a className somewhere?

  6. Just one little correction:

    Google Chrome v.23 (actual) doesn’t implement webkitFullScreenElement and webkitFullScreenEnabled. It implements webkitFullscreenElement and webkitFullscreenEnabled (with lower case ‘S’). I can’t understand WHY they do that =P

  7. Is there any way to launch full screen on page load?
    something like:

    jQuery(document).ready(function(){
    //launch fullscreen code
    })

Be Heard

Tip: Wrap your code in <code> tags...and don't flame others.

Use Code Editor
Older
Multi-Line JavaScript Strings
Newer
Square Search Boxes in WebKit