useFullscreen

Enters, exits, and tracks Fullscreen API state for the document or a target element.

stablerooks

Import

import { useFullscreen } from "rooks";

TypeScript signature

useFullscreen(props?: UseFullscreenProps): { isFullscreenAvailable: boolean; fullscreenElement: Element | null; isFullscreenEnabled: boolean; enableFullscreen: () => Promise<void>; disableFullscreen: () => Promise<void>; toggleFullscreen: () => Promise<void>; }

About

useFullscreen wraps the standard Fullscreen API and its older prefixed variants. It reports support and active state, and exposes promise-returning controls for the whole document or a supplied element ref.

Example

import { useRef, useState, type RefObject } from "react";
import { useFullscreen } from "rooks";

export default function FullscreenCard() {
  const cardRef = useRef<HTMLDivElement>(null);
  const [message, setMessage] = useState("");
  const fullscreen = useFullscreen({
    target: cardRef as RefObject<Element>,
    onError: () => setMessage("The browser reported a fullscreen error."),
  });

  async function toggle() {
    try {
      setMessage("");
      await fullscreen.toggleFullscreen();
    } catch (error) {
      setMessage(error instanceof Error ? error.message : "Fullscreen failed");
    }
  }

  return (
    <section>
      <div
        ref={cardRef}
        style={{ padding: 24, background: "white", color: "black" }}
      >
        <p>
          {fullscreen.isFullscreenEnabled
            ? "Fullscreen is active"
            : "Inline view"}
        </p>
        <button
          type="button"
          onClick={() => void toggle()}
          disabled={!fullscreen.isFullscreenAvailable}
        >
          {fullscreen.isFullscreenEnabled
            ? "Exit fullscreen"
            : "Enter fullscreen"}
        </button>
      </div>
      {message && <p role="alert">{message}</p>}
    </section>
  );
}

Parameters

The optional props object contains:

Property	Type	Default	Description
`target`	`RefObject<Element>`	document root	Element to request fullscreen for.
`onChange`	`(event: Event) => void`	none	Called after a fullscreen-change event.
`onError`	`(event: Event) => void`	none	Called after a fullscreen-error event.
`requestFullScreenOptions`	`FullscreenOptions`	none	Passed to `requestFullscreen()`.

The published target type is RefObject<Element>. Current React typings infer a nullable element ref before commit, which is why the example narrows the ref with a type assertion at the hook boundary.

Return value

Returns an object with:

isFullscreenAvailable: support detected after the first client effect.
fullscreenElement: the browser's active fullscreen element, initially null.
isFullscreenEnabled: whether an element is currently fullscreen.
enableFullscreen(), disableFullscreen(), and toggleFullscreen(): operations returning Promise<void>.

Behavior and lifecycle

Availability starts as false and is populated after mount. State updates in response to the detected standard or vendor-prefixed change/error events, not merely when a control is called. Event listeners are replaced when callbacks change and removed on unmount.

Control promises reject when the DOM is unavailable, the API is unsupported, or the browser rejects the request. enableFullscreen() uses document.documentElement when no target exists. toggleFullscreen() exits whichever element the document currently reports as fullscreen.

Compatibility and accessibility

Rendering is server-safe, but calling a control on the server throws a DOM-unavailable error. Browsers normally require enableFullscreen() to run directly from a trusted user action, and permissions policy or user settings can deny it. Users can usually exit with Escape even when application state has not yet updated.

Keep the trigger keyboard accessible, retain visible focus inside fullscreen content, and do not trap users in the mode. Handle promise rejections as well as onError. See SSR and browser APIs.

usePictureInPictureApi manages a floating video window.
useVideo includes a minimal fullscreen toggle for its video ref.