Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sindresorhus/screenfull

Simple wrapper for cross-browser usage of the JavaScript Fullscreen API
https://github.com/sindresorhus/screenfull

Last synced: 5 days ago
JSON representation

Simple wrapper for cross-browser usage of the JavaScript Fullscreen API

Awesome Lists containing this project

README 

        
# screenfull



> Simple wrapper for cross-browser usage of the JavaScript [Fullscreen API](https://developer.mozilla.org/en/DOM/Using_full-screen_mode), which lets you bring the page or any element into fullscreen. Smoothens out the browser implementation differences, so you don't have to.



**This package is ESM. Please [familiarize](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) yourself with what that implies.**\

If you cannot use ESM or need to support older browsers without using transpilation, use version 5.2.0.



**[Not supported on iPhone](#support)**



**This package is feature complete. No new features will be accepted.**



#### [Demo](https://sindresorhus.com/screenfull)



## Install



Only 0.7 kB gzipped.



```sh

npm install screenfull

```



Also available on [cdnjs](https://cdnjs.com/libraries/screenfull.js/5.1.0) *(older version)*.



## Why?



### Screenfull



```js

import screenfull from 'screenfull';



if (screenfull.isEnabled) {

	screenfull.request();

}

```



### Vanilla JavaScript



```js

document.fullscreenEnabled =

	document.fullscreenEnabled ||

	document.mozFullScreenEnabled ||

	document.documentElement.webkitRequestFullScreen;



function requestFullscreen(element) {

	if (element.requestFullscreen) {

		element.requestFullscreen();

	} else if (element.mozRequestFullScreen) {

		element.mozRequestFullScreen();

	} else if (element.webkitRequestFullScreen) {

		element.webkitRequestFullScreen(Element.ALLOW_KEYBOARD_INPUT);

	}

}



if (document.fullscreenEnabled) {

	requestFullscreen(document.documentElement);

}



// This is not even entirely comprehensive. There's more.

```



## Support



[Supported browsers](https://caniuse.com/#feat=fullscreen)



**Note:** Safari is supported on desktop and iPad, but not on iPhone. This is a limitation in the browser, not in Screenfull.



## Documentation



### Examples



#### Fullscreen the page



```js

import screenfull from 'screenfull';



document.getElementById('button').addEventListener('click', () => {

	if (screenfull.isEnabled) {

		screenfull.request();

	} else {

		// Ignore or do something else

	}

});

```



#### Fullscreen an element



```js

import screenfull from 'screenfull';



const element = document.getElementById('target');



document.getElementById('button').addEventListener('click', () => {

	if (screenfull.isEnabled) {

		screenfull.request(element);

	}

});

```



#### Hide navigation user-interface on mobile devices



```js

import screenfull from 'screenfull';



const element = document.getElementById('target');



document.getElementById('button').addEventListener('click', () => {

	if (screenfull.isEnabled) {

		screenfull.request(element, {navigationUI: 'hide'});

	}

});

```



#### Fullscreen an element with jQuery



```js

import screenfull from 'screenfull';



const element = $('#target')[0]; // Get DOM element from jQuery collection



$('#button').on('click', () => {

	if (screenfull.isEnabled) {

		screenfull.request(element);

	}

});

```



#### Toggle fullscreen on a image with jQuery



```js

import screenfull from 'screenfull';



$('img').on('click', event => {

	if (screenfull.isEnabled) {

		screenfull.toggle(event.target);

	}

});

```



#### Detect fullscreen change



```js

import screenfull from 'screenfull';



if (screenfull.isEnabled) {

	screenfull.on('change', () => {

		console.log('Am I fullscreen?', screenfull.isFullscreen ? 'Yes' : 'No');

	});

}

```



Remove listeners with:



```js

import screenfull from 'screenfull';



screenfull.off('change', callback);

```



#### Detect fullscreen error



```js

import screenfull from 'screenfull';



if (screenfull.isEnabled) {

	screenfull.on('error', event => {

		console.error('Failed to enable fullscreen', event);

	});

}

```



See the [demo](https://sindresorhus.com/screenfull) for more examples, and view the source.



#### Fullscreen an element with Angular.js



You can use the [Angular.js binding](https://github.com/hrajchert/angular-screenfull) to do something like:



```html



	
This is a fullscreen element


	Toggle fullscreen



```



#### Fullscreen the page with Angular 2



```ts

import {Directive, HostListener} from '@angular/core';

import screenfull from 'screenfull';



@Directive({

	selector: '[toggleFullscreen]'

})

export class ToggleFullscreenDirective {

	@HostListener('click') onClick() {

		if (screenfull.isEnabled) {

			screenfull.toggle();

		}

	}

}

```



```html

Toggle fullscreen

```



### API



#### .request(element, options?)



Make an element fullscreen.



Accepts a DOM element and [`FullscreenOptions`](https://developer.mozilla.org/en-US/docs/Web/API/FullscreenOptions).



The default element is ``. If called with another element than the currently active, it will switch to that if it's a descendant.



If your page is inside an `` you will need to add a `allowfullscreen` attribute (+ `webkitallowfullscreen` and `mozallowfullscreen`).



Keep in mind that the browser will only enter fullscreen when initiated by user events like click, touch, key.



Returns a promise that resolves after the element enters fullscreen.



#### .exit()



Brings you out of fullscreen.



Returns a promise that resolves after the element exits fullscreen.



#### .toggle(element, options?)



Requests fullscreen if not active, otherwise exits.



Accepts a DOM element and [`FullscreenOptions`](https://developer.mozilla.org/en-US/docs/Web/API/FullscreenOptions).



Returns a promise that resolves after the element enters/exits fullscreen.



#### .on(event, function)



Events: `'change' | 'error'`



Add a listener for when the browser switches in and out of fullscreen or when there is an error.



#### .off(event, function)



Remove a previously registered event listener.



#### .onchange(function)



Alias for `.on('change', function)`



#### .onerror(function)



Alias for `.on('error', function)`



#### .isFullscreen



Returns a boolean whether fullscreen is active.



#### .element



Returns the element currently in fullscreen, otherwise `undefined`.



#### .isEnabled



Returns a boolean whether you are allowed to enter fullscreen. If your page is inside an `` you will need to add a `allowfullscreen` attribute (+ `webkitallowfullscreen` and `mozallowfullscreen`).



#### .raw



Exposes the raw properties (prefixed if needed) used internally: `requestFullscreen`, `exitFullscreen`, `fullscreenElement`, `fullscreenEnabled`, `fullscreenchange`, `fullscreenerror`



## FAQ



### How can I navigate to a new page when fullscreen?



That's not supported by browsers for security reasons. There is, however, a dirty workaround. Create a seamless iframe that fills the screen and navigate to the page in that instead.



```js

import screenfull from 'screenfull';



document.querySelector('#new-page-button').addEventListener(() => {

	const iframe = document.createElement('iframe')



	iframe.setAttribute('id', 'external-iframe');

	iframe.setAttribute('src', 'https://new-page-website.com');

	iframe.setAttribute('frameborder', 'no');

	iframe.style.position = 'absolute';

	iframe.style.top = '0';

	iframe.style.right = '0';

	iframe.style.bottom = '0';

	iframe.style.left = '0';

	iframe.style.width = '100%';

	iframe.style.height = '100%';



	document.body.prepend(iframe);

	document.body.style.overflow = 'hidden';

});

```



## Resources



- [Using the Fullscreen API in web browsers](https://hacks.mozilla.org/2012/01/using-the-fullscreen-api-in-web-browsers/)

- [MDN - Fullscreen API](https://developer.mozilla.org/en/DOM/Using_full-screen_mode)

- [W3C Fullscreen spec](https://fullscreen.spec.whatwg.org/)

- [Building an amazing fullscreen mobile experience](https://developers.google.com/web/fundamentals/native-hardware/fullscreen/)