DOCSEARCHbyAlgolia
Submit Docs

screenfull

repository·main·Indexed 27 days ago

https://github.com/sindresorhus/screenfull

A lightweight, cross-browser wrapper for the JavaScript Fullscreen API (version 6.0.2). It provides a consistent interface to request, exit, or toggle fullscreen mode for the page or specific DOM elements, and includes utilities to check fullscreen status via isFullscreen and isEnabled, as well as event listeners for state changes and errors.

Tokens
1.3K
Snippets
4
Records
13
Agent score
43%

What's inside screenfull

  2. Access raw Fullscreen API properties

    main

    The .raw property exposes the underlying browser properties used internally, including vendor prefixes where necessary:

    • requestFullscreen
    • exitFullscreen
    • fullscreenElement
    • fullscreenEnabled
    • fullscreenchange
    • fullscreenerror

  4. Request fullscreen for the page or an element

    main

    Use .request(element, options?) to make an element fullscreen. If no element is provided, it defaults to <html> (the page).

    Important: Browsers only allow entering fullscreen when initiated by user events (e.g., click, touch, keydown).

    If your page is inside an <iframe>, you must add the allowfullscreen attribute (plus webkitallowfullscreen and mozallowfullscreen).

    Returns a promise that resolves after the element enters fullscreen.

    import screenfull from 'screenfull';

// Fullscreen the page
if (screenfull.isEnabled) {
	screenfull.request();
}

// Fullscreen a specific element
const element = document.getElementById('target');
if (screenfull.isEnabled) {
	screenfull.request(element, {navigationUI: 'hide'});
}

  5. Listen for fullscreen change events

    main

    Use .on('change', callback) or the alias .onchange(callback) to detect when the browser switches in and out of fullscreen mode. Use .off('change', callback) or .onchange to remove the listener.

    Use .on('error', callback) or the alias .onerror(callback) to detect errors during fullscreen transitions.

    import screenfull from 'screenfull';

if (screenfull.isEnabled) {
	screenfull.on('change', () => {
		console.log('Am I fullscreen?', screenfull.isFullscreen ? 'Yes' : 'No');
	});
}

// Remove listener
screenfull.off('change', callback);

  6. Toggle fullscreen mode

    main

    Use .toggle(element, options?) to request fullscreen if it is not currently active, or exit if it is. Accepts a DOM element and FullscreenOptions. Returns a promise that resolves after the state change.

    import screenfull from 'screenfull';

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

// Toggle fullscreen on an element
if (screenfull.isEnabled) {
	screenfull.toggle(element);
}

  7. Check fullscreen status and capabilities

    main

    Use the following properties to inspect the current state:

    • isEnabled: Returns a boolean indicating if the browser allows entering fullscreen (check if your page is in an <iframe> with allowfullscreen).
    • isFullscreen: Returns a boolean indicating if fullscreen is currently active.
    • element: Returns the DOM element currently in fullscreen, or undefined if not in fullscreen.

  8. Request fullscreen mode with request()

    main
    Use request(element, options) to enter fullscreen mode. By default, it targets document.documentElement. It returns a Promise that resolves when the fullscreen transition is complete. You can pass an optional options object (e.g., for allowPointerLock).

  11. Listen to fullscreen change and error events

    main

    You can subscribe to fullscreen state changes and errors using the following methods:

    • onchange(callback): Invokes the callback when the fullscreen state changes.
    • onerror(callback): Invokes the callback when a fullscreen error occurs.
    • on(event, callback): A generic method to listen for 'change' or 'error' events.
    • off(event, callback): Removes a previously registered event listener.