wholescreen.js

Tiny wrapper (~40 lines of code) for the Fullscreen API.

• Handles all vendor prefixes for you
• Has a simple API that resembles the standard API
• Supports UMD, standalone ES6 modules, require.js and AMD as separate files so you can import it anwhere.
• Comes with TypeScript definitions (since it's written in TypeScript)
• Detects each of the browser properties individually, meaning wider support, and safer for browser changes. All while using less code.
• Probably the smallest Fullscreen API wrapper (but they're all pretty small)

Installation

npm install --save wholescreen.js

Or

yarn add wholescreen.js

Or you can use the jsdelivr CDN

<script src="https://cdn.jsdelivr.net/npm/wholescreen.js"></script>

Usage example

import wholescreen from 'wholescreen.js';

const element = document.querySelector('.some-element');

// Check for support
if (wholescreen.supported) {
	// listen to changes
	wholescreen.on('change', () => {
		// Log change based on `wholescreen.active`
		console.log(`Fullscreen ${wholescreen.active ? 'enabled' : 'disabled'}`)
	});

	// Activate fullscreen mode on button click
	// You should only request fullscreen from events like this, or browsers will deny the request.
	document.querySelector('.button').addEventListener('click', () => {
		// If you pass an element as the second argument the element will fullscreen instead of the window
		wholescreen.request();
	});
}

API

The API was designed to generally use the same names as the standard API (without the word fullscreen in everything since it's implied). There is one exception: fullscreenEnabled was renamed to supported, to avoid the misleading standard name. It also has a couple of useful additions over the standard API.

Getters

| Property | type | Description | |-------------|-----------|---------------| | supported | boolean | Check device / browser support and if the window has permission to use fullscreen (requires special parameter for iframes) | | active | boolean | Check if an element is currently fullscreened | | element | Node | The dom node (element) currently fullscreened (or null if none) |

Methods

| Method | arguments | Description | |-------------|-------------------------------|---------------| | request() | element | Activate fullscreen for the element, or the window if the element argument is missing | | toggle() | element, enable | Toggle fullscreen for the element. Will toggle based on the optional enable argument if present, otherwise it will reverse active. If another element is fullscreened, it will restore it first | | exit() | - | Exit fullscreen | | on() | type, listener, options | Listen for wholescreen events. Works exactly like addEventListener, except it (only) supports custom wholescreen event types change and error | | off() | type, listener, options | Remove wholescreen event listener. Works exactly like removeEventListener, except it (only) supports custom wholescreen event types change and error |

Browser API

If you need to get the original method and property names for the current browser, these are available as wholescreen.events and wholescreen.props

Support

Browsers support

Alternatives

• screenfull.js - The first and most well used Fullscreen API wrapper. Uses commonjs module declaration. The wholescreen.js API is very similar to screenfull.js (not by intention). screenfull also support the legacy syntax with an additional optional argument for allowing keyboard input.
• fscreen - Small alternative. Handles all the common prefixes, but not the older Safari ones (you can most likely do without them). Uses es6-module declaration. The API is more verbose than screenfull.js and wholescreen.js