Browser Fullscreen APIs

Published by on

under JavaScript, TIL and Browser

Browser Fullscreen APIs

Even though I have used browser fullscreen APIs from time to time in some of my projects, I was still unaware of some of the details.

That's why I've compiled some useful code snippets below.

Prefixed methods and objects

According to caniuse the fullscreen API in Safari is still prefixed. It is necessary to prefix the method name with webkit; so in Safari you have to call e.g. element.webkitRequestFullscreen() instead of element.requestFullscreen().

I use the following helper function to call the correct method or access the correct object in each browser:

function getPrefixedElementMethod(el, methodName) {
	const prefixedMethodName = getPrefixedName(el, methodName);
	return prefixedMethodName && typeof el[prefixedMethodName] === 'function'
		? (...args) => el[prefixedMethodName](...args)
		: undefined;
}

function getPrefixedChild(parent, childName) {
	const prefixedChildName = getPrefixedName(parent, childName);
	return prefixedChildName ? parent[prefixedChildName] : undefined;
}

function getPrefixedName(parent, childName) {
	const prefixes = ['webkit', 'moz', 'ms'];

	const prefixedChildName = prefixes.reduce((result, prefix) => {
		if (typeof parent[childName] !== 'undefined') {
			return childName;
		} else {
			const prefixedChildName = `${prefix}${capitalizeFirstLetter(
				childName
			)}`;

			if (typeof parent[prefixedChildName] !== 'undefined') {
				return prefixedChildName;
			}
		}

		return result;
	}, null);

	return prefixedChildName;
}

function capitalizeFirstLetter(str) {
	return str.charAt(0).toUpperCase() + str.slice(1);
}

Open element in fullscreen

The requestFullscreen() method can be used to open an element in fullscreen mode.

The method has an optional options parameter which allows to specify whether browser navigation elements are shown or not (exceptions: Firefox and Safari).

The method returns a Promise allowing you to react to the switch of fullscreen mode, and e.g. execute code after the switch (exception: Safari).

const element = document.querySelector('#my-fullscreen-element');

// default
element.requestFullscreen();

// hide browser navigation UI
element.requestFullscreen({ navigationUI: 'hide' });

// show browser navigation UI
element.requestFullscreen({ navigationUI: 'show' });

// requestFullscreen returns a promise
element.requestFullscreen().then(() => {
	console.log('you are now in fullscreen mode');
});

// cross-browser method
const requestFullScreen = getPrefixedElementMethod(
	element,
	'requestFullScreen'
);
requestFullScreen();
requestFullScreen({ navigationUI: 'hide' }).then(() => {
	console.log('opened fullscreen');
});

Close fullscreen mode

The document.exitFullscreen() method closes the fullscreen mode. Keep in mind that exitFullscreen is a method of the document object, not the element object.

The document.exitFullscreen() also returns a Promise (exception: Safari).

// default
document.exitFullscreen();

// exitPromise returns a Promise
document.exitFullscreen().then(() => {
	console.log('full screen was closed');
});

// cross-browser method
const exitFullScreen = getPrefixedElementMethod(document, 'exitFullScreen');
exitFullScreen();
exitFullScreen().then(() => {
	console.log('closed fullscreen');
});

Detect fullscreen mode

The object document.fullscreenElement contains a reference to the element that was opened in fullscreen mode. In Safari this object is prefixed: document.webkitFullscreenElement (exception Safari on iPhone: this object does not exist here).

// detect fullscreen
if (document.fullscreenElement) {
	console.log('hello fullscreen.');
}

// cross-browser (except Safari Iphone)
if (getPrefixedChild(document, 'fullscreenElement')) {
	console.log('hello fullscreen.');
}

Events

When opening or closing the fullscreen mode, the fullscreenchange event is fired. In Safari, the event name is prefixed with webkitfullscreenchange.

function fullscreenChanged() {
	console.log('fullscreen was either opened or closed.');
}

document.addEventListener('fullscreenchange', fullscreenChanged);

Example

In the following example I included all code snippets

More articles:

Leave a comment

Available formatting commands

Use Markdown commands or their HTML equivalents to add simple formatting to your comment:

Text markup
*italic*, **bold**, ~~strikethrough~~, `code` and <mark>marked text</mark>.
Lists
- Unordered item 1
- Unordered list item 2
1. Ordered list item 1
2. Ordered list item 2
Quotations
> Quoted text
Code blocks
```
// A simple code block
```
```php
// Some PHP code
phpinfo();
```
Links
[Link text](https://example.com)
Full URLs are automatically converted into links.

Replied on your own website? Send a Webmention!