Is your Fullscreen API code up to date? Find out how to make it work the same in modern browsers

With the introduction of IE11, all major browsers now support the Fullscreen API. However, due to prefixes and differences between the specification and early implementations, you may need to update any code you have that makes use of this feature. When I looked through the top search results on Google, none of the results showed both the latest syntax for all features and the ms prefix. In this post I’ll show you what has changed and what needs updating.

This article won’t cover how to use the Fullscreen API, as there are plenty of articles out there already. Just do a quick Google search if you need to get up to speed, but make sure to come back here, as most are out of date.

Syntax changes between early implementations and the specification

The changes in syntax are relatively minor, but it is important to get right if you want the fullscreen API to work in the widest range of browsers.

JavaScript API

If you’re using the fullscreenchange event no change is required except for adding all the prefixes (see below.)

For most of the attributes and methods the only change is that the “s” in “fullscreen” is now lowercase. It is uppercase in Firefox and WebKit/Blink browsers (later versions of WebKit/Blink support both.) A more substantial change is that the cancelFullScreen() method for exiting fullscreen mode was specified as exitFullScreen() in the specification.

Here is a handy table of the changes. All browsers currently require prefixes with both versions, so remember that the initial character should be capitalised: msExitFullScreen() instead of exitFullScreen(); mozCancelFullScreen instead of cancelFullScreen(), and so on.

The new syntax should currently be used unprefixed (for Opera 12.1 and the future), and prefixed for WebKit/Blink and IE.

CSS

While the JavaScript API just received a little renaming, the CSS capabilities also were expanded somewhat.

Browsers except for IE support the :full-screen pseudo class for giving styles to an element when it is in fullscreen mode. This was changed in the spec to :fullscreen. IE11 is currently the only browser that supports the syntax in the spec. Opera 12.1 does too (without prefix), but this was dropped when switching to Blink.

Along with this change, a new pseudo element called ::backdrop was added to the spec, and is supported in IE11. This adds a pseudo element behind the fullscreen element, but above all other content on the page. This can then be styled, such as adding a fancy background effect. WebKit and Blink add a black backdrop but it can not be styled, while Firefox and Opera 12.1 don’t include a backdrop at all – if the element doesn’t cover the entire screen you can see the content below.

Here is a handy table. Again, remember the prefixes.

Include all the relevant prefixes

Now this is where things get ugly. The only browser not to require prefixes is Opera 12.1. For all other browsers you should use the regular vendor prefix you know and love.

IE only supports the standard syntax, so you can leave out the ms prefix for the non-standard syntax. Firefox doesn’t support the standard syntax, but you can either include moz with this syntax for future proofing, or just rely on the old syntax (it functionally behaves the same) until the prefix is dropped.

All modern WebKit and Blink desktop browsers support both the standard and non-standard syntax for JavaScript, and only the non-standard CSS :full-screen. As mobile browsers don’t support the spec and Chrome and Opera update rapidly I only use the modern spec. The only case you’ll need to use the non-standard syntax with the webkit prefix is if you need to support Safari 5.1. Although this is 3 versions old (4 if you include 6.1) it is currently the most popular version of Safari in StatCounter, Clicky, and Akamai stats.

The following code tests to see if the Fullscreen API is enabled using all the relevant prefixes, except Webkit’s version of the old syntax:

if (document.fullscreenEnabled || 
  document.webkitFullscreenEnabled || 
  document.msFullscreenEnabled ||
  document.mozFullScreenEnabled) {
  // add Fullscreen API code here. Remember all the prefixes
} else {
  // in reality you should use fallback code here
  alert("Your browser doesn’t support the fullscreen API");
}

Note that the standard syntax is used unprefixed as well as prefixed for WebKit/Blink and IE. The old syntax is uses for Firefox.

Browser differences with CSS styling

Although the JavaScript API more or less works the same in all browsers, CSS styling works quite differently.

In IE11, Firefox and Opera 12.1 the element is set to 100% width and height. If you’re making something such as an image fullscreen it will be stretched, ignoring the aspect ratio.

In WebKit/Blink browsers (including Opera 15+) the element is centred on the screen with a black backdrop. The backdrop can’t be styled.

In IE11 if you set the width and height while in fullscreen the element is positioned at the top left of the screen (at its original size if you set both to auto) with a dark backdrop filling the screen. In Firefox the width and height are ignored. In Opera 12.1 (if you give it a high enough specificity) it will behave like IE11, but the backdrop is set to the size of the border-box of the element, so the rest of the page will be transparent.

The backdrop in IE11 can be styled with ::backdrop but can’t be made (semi) transparent. If you use a background color with an alpha channel it will layer that colour on top of the original backdrop colour.

Making all browsers stretch content to fill the screen

To make all browsers copy the Firefox style you need to add width of 100% to :-webkit-full-screen, and make it fixed position at the top of the screen. You may also want to add it to the prefixless version as we don’t know how browsers will implement this when prefixes are removed.

As WebKit/Blink keeps the original background colour for the element, if the image has transparent portions you may also want to set the background to none. I didn’t do this for the prefixless version in the demo below as this removes the backdrop entirely in Opera 12.1. Note that while Opera now uses Blink, Opera 12.1 (based on Presto) is by far and away the most popular Opera version on any stats sites (as it doesn’t update to Opera 15+), so it is still worth taking care of any differences.

Another enhancement you probably want to do is add object-fit so that any image or video isn’t stretched. Opera 12.1 (the only browser to currently support this and the Fullscreen API) requires the -o- prefix. Although this is mentioned in the spec, Opera doesn’t apply it by default.

:-webkit-full-screen {
  width: 100%;
  position: fixed;
  top: 0;

  /* webkit keeps the original background color, so reset */
  background: none;
}
:fullscreen {
  /* not currently needed, but just in case */
  width: 100%;
  height: 100%;
  position: fixed;
  top: 0;

  /* keeps correct aspect ratio and full image visible */
  -o-object-fit: contain; /* Opera 12.1 */
  object-fit: contain;
}

Here is a full screen demo with stretched content. It should work the same in every modern browser that supports the Fullscreen API.

Centring the content

Achieving WebKit’s default behaviour is slightly more difficult. If you only want it to also work in IE it is easy. Just add margin: auto; to :-ms-fullscreen, and set the width and height to auto to stop the content from being stretched.

:-ms-fullscreen {
  width: auto;
  height: auto;
  margin: auto;
}

Here is a simple centred fullscreen demo using this technique. It should be consistent in IE11 and WebKit/Blink browsers. It will not work correctly in Firefox and Opera 12.1 for reasons mentioned previously.

Instead the easiest way to do it is make the parent element fullscreen instead of the actual element (figure rather than img in my demo .) Then you can style the parent as the backdrop and positing the content inside it using your favourite CSS centring method. In my case I used flexbox, but you could use table layout or whatever.

 :-moz-full-screen {
  display: flex;
  align-items: center;
  justify-content: center;
}

:-ms-fullscreen {
  display: flex;
  align-items: center;
  justify-content: center;
}

:fullscreen {
  /* set to flexbox to centre imagine inside */
  display: flex;
  align-items: center;
  justify-content: center;
}

Now the child element(s) will be centred. Note that there is no need to set the width and height of the img element now as it is the parent being stretched not the image itself.

Try it out in the cross browser version of the previous example. This should work the same in all recent browsers that support the Fullscreen API. You can also add the older syntax of Flexbox with -moz- prefix, and the webkit version of the old Fullscreen API if you want even further support.

A quick demo pulling it all together

While showing a single transparent image being set to fullscreen is all well and good, I’ve made a slightly more complex version that allows any image in a gallery to be set to fullscreen. For this I‘ve adapted the demo I made for my Scrolling Snap Points article.

Here is the Fullscreen API gallery demo in action. Try clicking an image to have it go into fullscreen mode at its natural size, and click it again to close it.

The code shows almost all of the features of the API, so you can see how all the prefixes and syntax changes should work:

if (document.fullscreenEnabled || 
  document.webkitFullscreenEnabled || 
  document.msFullscreenEnabled ||
  document.mozFullScreenEnabled) {

  var imgs = document.getElementsByTagName("figure");

  for (var i = 0; i < imgs.length; i++) {
        imgs[i].addEventListener("click", function (event) {
        if (!document.fullscreenElement &&
            !document.webkitFullscreenElement &&
            !document.msFullscreenElement &&
            !document.mozFullScreenElement) { 
              if (this.requestFullscreen) {
                  this.requestFullscreen();
              } else if (this.webkitRequestFullscreen) {
                this.webkitRequestFullscreen();
              } else if (this.msRequestFullscreen) {
                this.msRequestFullscreen();
              } else if (this.mozRequestFullScreen) {
                this.mozRequestFullScreen();
              }
          } else {  
            if (document.exitFullscreen) {
              document.exitFullscreen();
            } else if (document.webkitExitFullscreen) {
              document.webkitExitFullscreen();
            } else if (document.msExitFullscreen) {
              document.msExitFullscreen();
            } else if (document.mozCancelFullScreen) {
              document.mozCancelFullScreen();
            }
          }
        }, false);
      }
    } else {
      // in reality you should use fallback code here
      alert("Your browser doesn’t support the fullscreen API");
    }

The CSS is more complex and perhaps more real world. As I want Firefox to behave the same as WebKit/Blink, I’m setting the figure to fullscreen rather than the image. As both of these elements have been styled as part of the gallery I can use the :fullscreen pseudo class to reset the styling, including setting the images back to their original size.

#gallery :fullscreen {
  /* unset styles. all: unset; would be nice here */
  background: black; /* Opera needs a bg colour  */
  border: none;
  box-shadow: none;
  margin: 0;

  /* set to flexbox to centre image inside */
  display: flex;
  align-items: center;
  justify-content: center;
}

I can also hide the figcaption:

:fullscreen figcaption {
  display: none;
}

Although WebKit/Blink sets the images as centred by default when in fullscreen, I still need to apply flexbox to them in this demo as the layout gets screwed up when exiting fullscreen without it for some reason. Sadly Safari still requires the webkit prefix so those need to be included too.

Lastly I used the ::backdrop pseudo class to style the backdrop in IE11 and any browser that supports the unprefixed version (none as yet.) This wasn’t really needed but shows what can be done:

#gallery :-ms-fullscreen::-ms-backdrop { 
  background: radial-gradient(at center, grey, black);        
}
#gallery :fullscreen::backdrop { 
  background: radial-gradient(at center, grey, black);        
}

Support information

I’ve covered browser support in the prose of this article, but it is always handy to have that info in a table. For this you can check out my Fullscreen API and Fullscreen CSS support tables.

At the time of writing the spec is fully supported by IE11, partially supported by Chrome, Opera, and Safari 6+, and partial supported with a different syntax by Firefox.

Wrap up

Pulling it all together, here is a checklist you can go through to update your Fullscreen API support.

• Make sure you include the non-prefixed syntax:
  • lowercase the “s” in fullscreen/Fullscreen.
  • change cancel to exit.
  • remove hyphen from :fullscreen pseudo class.
• Considering updating webkit prefixed code to the specification syntax. You will still need to use the old syntax for the :full-screen pseudo class.
• Add ms/-ms- prefixes for the standard syntax JavaScript and CSS
• Consider styling differences between browsers and update the CSS as appropriate.

Once you’ve done this you should be good to go, unless the syntax changes.