useFullscreen

Display an element full-screen

useFullscreen wraps the Fullscreen API to manage entering and exiting fullscreen mode for a given DOM element. It returns a tuple of the current fullscreen state (boolean) and an actions object with enterFullscreen, exitFullscreen, toggleFullscreen, and an isEnabled flag indicating browser support. Callbacks for enter/exit events are available via options.

When to Use

• Building video players, image galleries, or presentation modes that benefit from fullscreen display
• Creating immersive reading or gaming experiences that use the entire screen
• Adding a fullscreen toggle to data dashboards or visualization tools

Notes

• SSR-safe: Returns false for fullscreen state and isEnabled during server-side rendering. No document access occurs on the server.
• Browser support: The Fullscreen API is supported in all modern browsers. Check isEnabled to confirm support before showing fullscreen controls.
• User gesture: Browsers require a user-initiated event (e.g., a click) to enter fullscreen. Programmatic calls without user interaction will be rejected.

Usage

function Demo() {
  const ref = useRef(null);
  const [isFullscreen, { enterFullscreen, exitFullscreen, toggleFullscreen }]
    = useFullscreen(ref);
  return (
    <div ref={ref}>
      <div style={{ marginBottom: 16 }}>
        {isFullscreen ? "Fullscreen" : "Not fullscreen"}
      </div>
      <div>
        <button type="button" onClick={enterFullscreen}>
          enterFullscreen
        </button>
        <button
          type="button"
          onClick={exitFullscreen}
          style={{ margin: "0 8px" }}
        >
          exitFullscreen
        </button>
        <button type="button" onClick={toggleFullscreen}>
          toggleFullscreen
        </button>
      </div>
    </div>
  );
};

API

useFullScreen

Returns

readonly [boolean, { readonly enterFullscreen: () => void; readonly exitFullscreen: () => void; readonly toggleFullscreen: () => void; readonly isEnabled: boolean; }]: A tuple with the following elements:

• whether the browser is in fullscreen.
• a object：
• enterFullscreen
• exitFullscreen
• toggleFullscreen
• isEnabled: whether the browser support fullscreen

Arguments

UseFullScreenOptions

BasicTarget

export type BasicTarget<T extends TargetType = Element> = (() => TargetValue<T>) | TargetValue<T> | MutableRefObject<TargetValue<T>>;

TargetValue

type TargetValue<T> = T | undefined | null;

TargetType

type TargetType = HTMLElement | Element | Window | Document | EventTarget;