fscreen: Cross-Browser Fullscreen API

Common errors

• Uncaught (in promise) DOMException: The request is not allowed by the user agent or the platform in the current context.

  cause `fscreen.requestFullscreen()` was called without a direct user gesture.
  fix Trigger `fscreen.requestFullscreen()` only from within an event handler directly tied to user interaction, such as a button's `click` event listener.

• TypeError: Cannot read properties of null (reading 'requestFullscreen') or TypeError: element.requestFullscreen is not a function

  cause The Fullscreen API (even with vendor prefixes) is not supported by the browser, or `fscreen` was not properly initialized/loaded.
  fix Verify browser support by checking `fscreen.fullscreenEnabled` before attempting fullscreen operations. Ensure `fscreen` is correctly imported and available in the scope where it's being used.

Warnings

• gotcha The Fullscreen API, and by extension `fscreen.requestFullscreen()`, requires a direct user gesture (e.g., a click event) to initiate fullscreen mode. Calling it programmatically without user interaction will generally result in a security error or a rejected promise.
  Fix: Ensure `fscreen.requestFullscreen(element)` is called within an event handler triggered directly by a user action, such as a click or keypress.
• gotcha Fullscreen operations (`requestFullscreen`, `exitFullscreen`) are asynchronous. The state of the fullscreen element (`fscreen.fullscreenElement`) does not change immediately after calling these methods. Always rely on the `fullscreenchange` event to confirm the actual fullscreen state.
  Fix: Implement a `fullscreenchange` event listener and check `fscreen.fullscreenElement` within its handler to accurately track when fullscreen mode is entered or exited.
• gotcha fscreen acts as a wrapper to unify vendor prefixes for the native Fullscreen API; it does not polyfill the API itself. If a browser completely lacks support for the Fullscreen API, fscreen will report `fscreen.fullscreenEnabled` as `false`, and its methods will not function.
  Fix: Always check `fscreen.fullscreenEnabled` before attempting any fullscreen operations. Provide fallback UI or functionality for browsers that do not support the Fullscreen API.

Install

• npm install fscreen npm
• yarn add fscreen yarn
• pnpm add fscreen pnpm

Imports

• fscreen
  wrong:

  import { fscreen } from 'fscreen';

  correct:

  import fscreen from 'fscreen';

  fscreen is exported as a default module. Using named imports like `{ fscreen }` will result in `undefined` or an error, as there is no named export for `fscreen`.
• fscreen
  wrong:

  const fscreen = require('fscreen');

  correct:

  import fscreen from 'fscreen';

  While fscreen can be consumed in CommonJS, its primary usage is in modern browser environments where ES Modules are standard. Direct CommonJS `require` will import an object with a `default` property (`require('fscreen').default`). For Node.js, ensure your environment supports ESM or use dynamic import.
• fscreen.addEventListener
  wrong:

  document.addEventListener('fullscreenchange', handler, false);

  correct:

  fscreen.addEventListener('fullscreenchange', handler, false);

  fscreen provides its own `addEventListener` and `removeEventListener` methods that automatically handle vendor prefixes for fullscreen events, replacing direct `document.addEventListener` calls for `fullscreenchange` and `fullscreenerror`.

Quickstart

This quickstart demonstrates how to check for Fullscreen API support, register for fullscreen change events, and request fullscreen mode for a specific element upon a user interaction, cleaning up when exiting.

import fscreen from 'fscreen';

const initFullscreen = () => {
  if (fscreen.fullscreenEnabled) {
    // Store a reference to the handler to remove it later if needed
    const fullscreenChangeHandler = () => {
      if (fscreen.fullscreenElement !== null) {
        console.log('Entered fullscreen mode');
        // Example: add a class to the body when in fullscreen
        document.body.classList.add('is-fullscreen');
      } else {
        console.log('Exited fullscreen mode');
        // Example: remove the class when exiting
        document.body.classList.remove('is-fullscreen');
        // Clean up the event listener if no longer needed
        // fscreen.removeEventListener('fullscreenchange', fullscreenChangeHandler, false);
      }
    };

    fscreen.addEventListener('fullscreenchange', fullscreenChangeHandler, false);

    const myElement = document.getElementById('my-fullscreen-target');
    const enterFullscreenButton = document.getElementById('enter-fullscreen-btn');

    if (myElement && enterFullscreenButton) {
      enterFullscreenButton.addEventListener('click', () => {
        fscreen.requestFullscreen(myElement);
      });
    } else {
      console.warn("Required elements (my-fullscreen-target or enter-fullscreen-btn) not found.");
    }

  } else {
    console.log('Fullscreen API is not supported by this browser.');
    const statusDiv = document.getElementById('fullscreen-status');
    if (statusDiv) {
      statusDiv.textContent = 'Fullscreen is not available.';
    }
  }
};

// Call initFullscreen after the DOM is loaded
document.addEventListener('DOMContentLoaded', initFullscreen);

// Example HTML for context:
// <div id="my-fullscreen-target" style="background: lightblue; width: 100%; height: 100%; display: flex; justify-content: center; align-items: center;">Content</div>
// <button id="enter-fullscreen-btn">Enter Fullscreen</button>
// <div id="fullscreen-status"></div>