{"id":17233,"library":"fscreen","title":"fscreen: Cross-Browser Fullscreen API","description":"fscreen is a small, vendor-agnostic JavaScript utility library that provides a unified interface to the browser's Fullscreen API. It abstracts away browser-specific prefixes (like `webkit` or `moz`) for methods and properties such as `requestFullscreen`, `exitFullscreen`, `fullscreenElement`, and event listeners like `fullscreenchange` and `fullscreenerror`. The current stable version is 1.2.0. As a lightweight wrapper, fscreen aims to simplify cross-browser fullscreen implementation without introducing significant overhead or polyfills. It doesn't have a strict release cadence, typically releasing new versions as needed to adapt to browser changes or fix issues. Its primary differentiator is its simplicity and focus on providing a direct, standardized access layer to the native Fullscreen API, ensuring consistent behavior across different browsers without requiring developers to manage vendor prefixes manually.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/rafgraph/fscreen","tags":["javascript","fullscreen","browser"],"install":[{"cmd":"npm install fscreen","lang":"bash","label":"npm"},{"cmd":"yarn add fscreen","lang":"bash","label":"yarn"},{"cmd":"pnpm add fscreen","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"import { fscreen } from 'fscreen';","symbol":"fscreen","correct":"import fscreen from 'fscreen';"},{"note":"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.","wrong":"const fscreen = require('fscreen');","symbol":"fscreen","correct":"import fscreen from 'fscreen';"},{"note":"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`.","wrong":"document.addEventListener('fullscreenchange', handler, false);","symbol":"fscreen.addEventListener","correct":"fscreen.addEventListener('fullscreenchange', handler, false);"}],"quickstart":{"code":"import fscreen from 'fscreen';\n\nconst initFullscreen = () => {\n  if (fscreen.fullscreenEnabled) {\n    // Store a reference to the handler to remove it later if needed\n    const fullscreenChangeHandler = () => {\n      if (fscreen.fullscreenElement !== null) {\n        console.log('Entered fullscreen mode');\n        // Example: add a class to the body when in fullscreen\n        document.body.classList.add('is-fullscreen');\n      } else {\n        console.log('Exited fullscreen mode');\n        // Example: remove the class when exiting\n        document.body.classList.remove('is-fullscreen');\n        // Clean up the event listener if no longer needed\n        // fscreen.removeEventListener('fullscreenchange', fullscreenChangeHandler, false);\n      }\n    };\n\n    fscreen.addEventListener('fullscreenchange', fullscreenChangeHandler, false);\n\n    const myElement = document.getElementById('my-fullscreen-target');\n    const enterFullscreenButton = document.getElementById('enter-fullscreen-btn');\n\n    if (myElement && enterFullscreenButton) {\n      enterFullscreenButton.addEventListener('click', () => {\n        fscreen.requestFullscreen(myElement);\n      });\n    } else {\n      console.warn(\"Required elements (my-fullscreen-target or enter-fullscreen-btn) not found.\");\n    }\n\n  } else {\n    console.log('Fullscreen API is not supported by this browser.');\n    const statusDiv = document.getElementById('fullscreen-status');\n    if (statusDiv) {\n      statusDiv.textContent = 'Fullscreen is not available.';\n    }\n  }\n};\n\n// Call initFullscreen after the DOM is loaded\ndocument.addEventListener('DOMContentLoaded', initFullscreen);\n\n// Example HTML for context:\n// <div id=\"my-fullscreen-target\" style=\"background: lightblue; width: 100%; height: 100%; display: flex; justify-content: center; align-items: center;\">Content</div>\n// <button id=\"enter-fullscreen-btn\">Enter Fullscreen</button>\n// <div id=\"fullscreen-status\"></div>","lang":"javascript","description":"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."},"warnings":[{"fix":"Ensure `fscreen.requestFullscreen(element)` is called within an event handler triggered directly by a user action, such as a click or keypress.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement a `fullscreenchange` event listener and check `fscreen.fullscreenElement` within its handler to accurately track when fullscreen mode is entered or exited.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always check `fscreen.fullscreenEnabled` before attempting any fullscreen operations. Provide fallback UI or functionality for browsers that do not support the Fullscreen API.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Trigger `fscreen.requestFullscreen()` only from within an event handler directly tied to user interaction, such as a button's `click` event listener.","cause":"`fscreen.requestFullscreen()` was called without a direct user gesture.","error":"Uncaught (in promise) DOMException: The request is not allowed by the user agent or the platform in the current context."},{"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.","cause":"The Fullscreen API (even with vendor prefixes) is not supported by the browser, or `fscreen` was not properly initialized/loaded.","error":"TypeError: Cannot read properties of null (reading 'requestFullscreen') or TypeError: element.requestFullscreen is not a function"}],"ecosystem":"npm","meta_description":null}