Native Fullscreen JavaScript API (plus jQuery plugin)

HTML5 <video> is great, but when it was first released, one of the big complaints was that it couldn’t do true FullScreen like Flash. Thankfully, this is changing and native FullScreen support is coming to most browsers in the next few months (no word from the Internet Explorer team Update on IE below #5))

The API is still heavily in flux especially since the W3C joined in this week. I spent some time working through the differences to implement FullScreen in MediaElement.js HTML5 video player, and it’s working great in Safari 5.1+, Chrome Canary Chrome 15+, or Firefox Nightly (go to about:config and set full-screen-api.enabled= true) and scheduled for Firefox 10. Below I’m going to try to explain how things evolved, where we are today, and then some code that you can play with.

Simple Demo Video Demo

A Brief History of the FullScreen API

1. The first native FullScreen implementation appeared in Safari 5.0 (and iOS) added a a webkitEnterFullScreen() function that only worked on <video> tags using Safari’s video controls (see Apple’s HTML5VideoElement).
2. For Safari 5.1, Apple changed the API to be more inline with Mozilla’s FullScreen API proposal (which actually predates Apple’s implementation). Now, webkitRequestFullScreen() can be called on any DOM element which makes that portion of an HTML page go fullscreen.
3. Firefox and Chrome announced that they will add FullScreen API support, and the feature has already arrived in Chrome Canary Chrome 15+ and Firefox Nightly (scheduled for Firefox 10). The Mozilla team has posted some a demo.
4. On October 15, 2011, the W3C released a Fullscreen API proposal (written by a member of the Opera team) which has two main differences from Mozilla’s proposal:
1. Mozilla/Webkit uses a Capital ‘S’ (FullScreen) while W3C does not (Fullscreen)
2. Mozilla/Webkit uses cancelFullScreen
   while W3C uses exitFullscreen
5. Update (11/15/2011): Ted Johnson from IEBlog says IE10 will not support the FullScreen API (12/05/2011: I misunderstood the first email from Ted) that the IE10 team has not yet decided whether to implement the FullScreen API. He notes however that, “Windows 8 Metro style Internet Explorer is always full screen … and as before, F11 enters full screen mode in desktop versions of IE.”

Understanding the FullScreen API

Here are the most important parts of the FullScreen API with notes on how things differ among browsers. In general, I’m using the Mozilla/Webkit spelling in the examples below, but I’m also noting the W3C differences where needed.

1. Detecting FullScreen support

To detect fullscreen support, you’ll need to use the typeof command to find out if a given browser has support for the FullScreen API methods. There is also boolean property called fullScreenEnabled that tells you if the user has disabled the feature (strangely WebKit does not have the fullScreenEnabled property making it difficult to detect if it’s turned off).

// Mozilla's proposed API: in practice, you'll need vendor prefixes (see examples below)
if (typeof document.cancelFullScreen != 'undefined' && document.fullScreenEnabled === true) {
    /* do fullscreen stuff */
}

2. Entering and Exiting FullScreen

To enter FullScreen mode, you call requestFullScreen (or requestFullscreen for W3C) on the element want to be viewed in FullScreen. To exit you call cancelFullScreen (or exitFullscreen for W3C) on the document object.

// mozilla proposal
element.requestFullScreen();
document.cancelFullScreen(); 

// Webkit (works in Safari and Chrome Canary)
element.webkitRequestFullScreen(); 
document.webkitCancelFullScreen(); 

// Firefox (works in nightly)
element.mozRequestFullScreen();
document.mozCancelFullScreen(); 

// W3C Proposal
element.requestFullscreen();
document.exitFullscreen();

Mozilla has also proposed an alternate requestFullScreenWithKeys() method which would enable the user to use the keyboard in FullScreen mode. With Flash, Adobe always disabled keyboard support in FullScreen to prevent malicious sites from attempting to steal passwords, but it looks like the browser makers are considering making this an option.

3. Fullscreen Event and Current Status

To detect when a FullScreen event happens, there is a fullscreeneventchange that fires on the element going FullScreen and a boolean property (fullScreen) on the document object that reports if it’s in FullScreen mode or not.

element.addEventListener('fullscreeneventchange', function(e) {
    if (document.fullScreen) {
       /* make it look good for fullscreen */
    } else {
       /* return to the normal state in page */
    }
}, true);

Mozilla also mentions the possibility of adding a fullscreendenied event in the future. You should also know that Webkit added an ‘Is’ to their boolean property and that the W3C proposal strangely does not include this property:

// Mozilla proposal
document.fullScreen;
// Firefox (Nightly)
document.mozFullScreen;
// Webkit (Chrome, Safari)
document.webkitIsFullScreen; // note the 'Is'
// W3C proposal
// None? Why?

4. Styling FullScreen

Both Mozilla and the W3C have proposed new pseudo CSS classes for styling elements in FullScreen mode.

/* normal state */
.my-container {
    width: 640px;
    height: 360px;
}

/* Mozilla proposal (dash) */
.my-container:full-screen {
    width:100%;
    height:100%;
}

/* W3C proposal (no dash) */
.my-container:fullscreen {
    width:100%;
    height:100%;
}

/* currently working vendor prefixes */
.my-container:-webkit-full-screen, .my-container:-moz-full-screen {
    width:100%;
    height:100%;
}

5. Embedding FullScreen

When you embed content from another site (like a YouTube video) using Flash’s <object><embed> tags, you can specificy whether or not to allow FullScreen to work. This feature has also been added to the <iframe> tag using the allowFullScreen attribute.

<!-- content from another site that is allowed to use the fullscreen command -->
<iframe src="http://anothersite.com/video/123" width="640" height="360" allowFullScreen></iframe>

Putting it All Together

To make this work in its current state, you need a wrapper that can help detect the right features. Here’s what I’ve put together to work in Safari 5.1, Chrome Canary Chrome 15+, and Firefox Nightly. I’ll update it if the W3C notation goes through:

(function() {
	var
		fullScreenApi = {
			supportsFullScreen: false,
			isFullScreen: function() { return false; },
			requestFullScreen: function() {},
			cancelFullScreen: function() {},
			fullScreenEventName: '',
			prefix: ''
		},
		browserPrefixes = 'webkit moz o ms khtml'.split(' ');

	// check for native support
	if (typeof document.cancelFullScreen != 'undefined') {
		fullScreenApi.supportsFullScreen = true;
	} else {
		// check for fullscreen support by vendor prefix
		for (var i = 0, il = browserPrefixes.length; i < il; i++ ) {
			fullScreenApi.prefix = browserPrefixes[i];

			if (typeof document[fullScreenApi.prefix + 'CancelFullScreen' ] != 'undefined' ) {
				fullScreenApi.supportsFullScreen = true;

				break;
			}
		}
	}

	// update methods to do something useful
	if (fullScreenApi.supportsFullScreen) {
		fullScreenApi.fullScreenEventName = fullScreenApi.prefix + 'fullscreenchange';

		fullScreenApi.isFullScreen = function() {
			switch (this.prefix) {
				case '':
					return document.fullScreen;
				case 'webkit':
					return document.webkitIsFullScreen;
				default:
					return document[this.prefix + 'FullScreen'];
			}
		}
		fullScreenApi.requestFullScreen = function(el) {
			return (this.prefix === '') ? el.requestFullScreen() : el[this.prefix + 'RequestFullScreen']();
		}
		fullScreenApi.cancelFullScreen = function(el) {
			return (this.prefix === '') ? document.cancelFullScreen() : document[this.prefix + 'CancelFullScreen']();
		}
	}

	// jQuery plugin
	if (typeof jQuery != 'undefined') {
		jQuery.fn.requestFullScreen = function() {

			return this.each(function() {
				if (fullScreenApi.supportsFullScreen) {
					fullScreenApi.requestFullScreen(this);
				}
			});
		};
	}

	// export api
	window.fullScreenApi = fullScreenApi;
})();

This creates an object called fullScreenApi with a boolean property supportsFullScreen and some methods that allow you to do something more universal. Here’s an example usage:

if (fullScreenApi.supportsFullScreen) {
	myButton.addEventListener('click', function() {
		fullScreenApi.requestFullScreen(someElement);
	}, true);
}

You can see it in action below:

Simple Demo Video Demo

Issues and Updates

Since this post, there are some additional things worth mentioning

• Security concerns – Browser vendors are well aware of the potential security issues with fullscreen. For example, a malicious site could show a full screen Windows or Mac login window and steal a password. That’s why they are disabling keyboard support by default and only enabling by explicitly asking.
• Internet Explorer support – I have an email from a IE team member saying they are discussing it, but have not made any decisions. As of now, IE10 will not implement the FullScreen API, the IE team has not yet decided if they will implement the FullScreen API.
• FullscreenEnabled vs. IsFullScreen – The W3C includes the very helpful fullscreenEnabled flag to let your code know if you can use the API, but strangely the W3C does not include an isFullscreen flag. WebKit on the other hand has webkitIsFullScreen, but does not have a webkitFullScreenEnabled equivalent property. Mozilla helpfully includes both.