# screenfull

> Simple wrapper for cross-browser usage of the JavaScript Fullscreen API, which lets you bring the page or any element into fullscreen.

Latest version **6.0.2** (published 2022-06-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install screenfull
pnpm add screenfull
yarn add screenfull
bun add screenfull
```

## Health

**Score 45/100 (D)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 6.0.2 |
| Published | 2022-06-19 |
| First published | 2013-09-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | ^14.13.1 \|\| >=16.0.0 |
| Dependencies | 0 |
| Unpacked size | 17.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7141 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | browser, fullscreen |

## Links

- npm: https://www.npmjs.com/package/screenfull
- Repository: https://github.com/sindresorhus/screenfull
- Homepage: https://github.com/sindresorhus/screenfull#readme
- Issues: https://github.com/sindresorhus/screenfull/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/screenfull

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 6.0.2 (latest) — 2022-06-19
- 6.0.1 — 2022-01-16
- 6.0.0 — 2021-11-03
- 5.2.0 — 2021-11-03
- 5.1.0 — 2020-12-24
- 5.0.2 — 2020-02-13
- 5.0.1 — 2020-01-19
- 5.0.0 — 2019-09-09
- 4.2.1 — 2019-07-27
- 4.2.0 — 2019-03-31
- 4.1.0 — 2019-03-19
- 4.0.1 — 2019-02-18
- 4.0.0 — 2018-12-15
- 3.3.3 — 2018-09-04
- 3.3.2 — 2017-10-27
- … 14 more at https://npm.io/package/screenfull/versions

## 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 that 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
<div ngsf-fullscreen>
	<p>This is a fullscreen element</p>
	<button ngsf-toggle-fullscreen>Toggle fullscreen</button>
</div>
```

#### 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
<button toggleFullscreen>Toggle fullscreen<button>
```

### 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 `<html>`. 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 `<iframe>` 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 `<iframe>` 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/)

---
_Source: https://npm.io/package/screenfull · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._