useFullscreen

useFullscreen

A robust hook that provides a cross-browser compatible way to make any specific DOM element (or the entire webpage) fullscreen. It handles vendor prefixes (webkit, moz, ms) automatically and strictly manages the browser's native Fullscreen API.

Usage Examples

Basic

Making a specific element take over the entire screen.

import { useFullscreen } from "react-hook-lab";

function MoviePlayer() {
  // By default, the ref types to an HTMLDivElement
  const { ref, isFullscreen, toggle } = useFullscreen();

  return (
    <div ref={ref} style={{ background: "black", color: "white", padding: 20 }}>
      <h2>Now Playing: React Hook Lab</h2>
      <button onClick={toggle}>
        {isFullscreen ? "Exit Fullscreen" : "Enter Fullscreen"}
      </button>
    </div>
  );
}

Common

Making the entire document (the whole webpage) fullscreen instead of a specific element.

import { useFullscreen } from "react-hook-lab";

function AppKioskMode() {
  // If you don't attach the `ref` to anything, `enter()` will automatically 
  // target `document.documentElement`, pushing the entire page to fullscreen!
  const { isFullscreen, enter, exit } = useFullscreen();

  return (
    <div>
      <p>App Status: {isFullscreen ? "Kiosk Mode" : "Windowed"}</p>
      
      {!isFullscreen ? (
        <button onClick={enter}>Launch Kiosk</button>
      ) : (
        <button onClick={exit}>Exit</button>
      )}
    </div>
  );
}

Advanced

Catching permissions errors (e.g., trying to trigger fullscreen without a direct user interaction, which browsers block).

import { useFullscreen, useTimeout } from "react-hook-lab";

function SneakyFullscreen() {
  const { isFullscreen, toggle, error } = useFullscreen();

  // Browsers block fullscreen requests that don't originate from a click/keypress.
  // This will fail, and populate the `error` state.
  useTimeout(toggle, 2000);

  return (
    <div>
      <button onClick={toggle}>Manual Toggle (Works)</button>
      {error && <p style={{ color: "red" }}>Error: {error.message}</p>}
    </div>
  );
}

API Reference

Return Object

Returns an object of type UseFullscreenReturn<T> containing:

• ref (RefObject<T>): A React ref to attach to the target element. (Defaults to HTMLDivElement).
• isFullscreen (boolean): True if the targeted element (or the document) is currently fullscreen.
• error (Error | null): Contains the browser's rejection error if a fullscreen request fails.
• enter (() => Promise<void>): Requests the browser to enter fullscreen mode. Must be called via user interaction (like a click).
• exit (() => Promise<void>): Exits fullscreen mode.
• toggle (() => Promise<void>): Switches between enter and exit automatically based on the current state.

Core Working

Because the Fullscreen API is historically fragmented, useFullscreen performs aggressive feature detection to find the correct vendor-prefixed methods (e.g., webkitRequestFullscreen, mozRequestFullScreen, msRequestFullscreen).

For state synchronization, the hook attaches event listeners to fullscreenchange (and its webkit, moz, and MS variants) directly on the document. This ensures that even if the user exits fullscreen by hitting the Esc key on their keyboard, the isFullscreen React state instantly flips back to false, keeping your UI perfectly synced with the browser's hardware state.