Solution

Treat the browser document as the authority: commands request transitions, while fullscreenchange reports what actually became true.

The problem, in plain English

Fullscreen is shared document state, not private component state. A request may be rejected, the user may press Escape, and another element may become fullscreen without this hook initiating it. The hook therefore needs commands for intent and one document listener for observed reality.

The mental model

Think of document.fullscreenElement as the single register that every hook reads. Each instance compares that shared value with its own current target; equality means active, while null or any other element means inactive.

A first attempt

const enter = async () => {
  await targetRef.current.requestFullscreen();
  setIsFullscreen(true);
};

const exit = async () => {
  await document.exitFullscreen();
  setIsFullscreen(false);
};

This looks natural because it updates state after each successful promise. It still misses Escape, browser UI, and changes started by other code. More subtly, promise completion is not the Fullscreen API's state notification; fullscreenchange is, so the local boolean can drift from the document.

The working solution

const { useCallback, useEffect, useState } = require('react');

function useFullscreen(targetRef) {
  const [isFullscreen, setIsFullscreen] = useState(false);

  useEffect(() => {
    // Re-read both sides on every event because the active element and the
    // ref's current target can each change during this mount.
    const syncFromDocument = () => {
      setIsFullscreen(document.fullscreenElement === targetRef.current);
    };

    syncFromDocument();
    document.addEventListener('fullscreenchange', syncFromDocument);

    return () => {
      document.removeEventListener('fullscreenchange', syncFromDocument);
    };
  }, []);

  const enter = useCallback(async () => {
    const target = targetRef.current;
    if (!target || typeof target.requestFullscreen !== 'function') {
      throw new Error('Fullscreen target or requestFullscreen is unavailable');
    }

    // State changes only when the browser dispatches fullscreenchange.
    await target.requestFullscreen();
  }, [targetRef]);

  const exit = useCallback(async () => {
    if (!document.fullscreenElement) return;

    if (typeof document.exitFullscreen !== 'function') {
      throw new Error('document.exitFullscreen is unavailable');
    }

    // A rejected exit leaves the event-derived state untouched.
    await document.exitFullscreen();
  }, []);

  const toggle = useCallback(async () => {
    if (document.fullscreenElement === targetRef.current) {
      await exit();
    } else {
      await enter();
    }
  }, [enter, exit, targetRef]);

  return { isFullscreen, enter, exit, toggle };
}

module.exports = { useFullscreen };

The effect performs an initial reconciliation and then owns one listener for the mount's full lifetime. The commands validate browser capabilities and await them, but deliberately never write isFullscreen; only a document snapshot observed at mount or on fullscreenchange can do that.

Walking through one call

Suppose a video element is the target and a sidebar is currently fullscreen:

1. The event-derived state is false because the sidebar is not the video.
2. toggle() compares document.fullscreenElement with targetRef.current. They differ, so it selects enter(), not exit().
3. enter() captures the current video element, verifies requestFullscreen, and awaits the browser request.
4. When the browser makes the video active, it dispatches fullscreenchange.
5. syncFromDocument now compares the video with itself and sets isFullscreen to true.
6. If the user later presses Escape, the document becomes empty and dispatches another event; the same comparison changes state back to false.

Complexity

Mounting, each command, and each fullscreenchange notification take O(1) time. Each mounted hook stores O(1) state and owns one document listener.

Gotchas

• Flipping a local boolean. Escape and external transitions bypass that boolean. Fix: calculate equality from document.fullscreenElement on every fullscreenchange.
• Treating any fullscreen element as this target. Boolean(document.fullscreenElement) answers a document-wide question. Fix: use strict equality with targetRef.current.
• Exiting when another element is active. A generic “something is fullscreen” toggle controls the wrong element. Fix: exit only on exact equality and enter otherwise.
• Updating after a resolved request. Resolution alone is not the state event and creates two competing update paths. Fix: await commands for completion, but let the event listener own state.
• Assuming APIs exist. jsdom, older browsers, and restricted elements may lack methods. Fix: throw explicit Error objects for unsupported operations, while keeping an already-empty exit a no-op.
• Leaking document listeners. A fresh cleanup callback cannot remove the subscribed function. Fix: create one named handler inside the effect and close over it in cleanup.

Going further

• Add fullscreenerror reporting so the UI can display failures initiated outside these command promises.
• Accept an options object for requestFullscreen({ navigationUI: 'hide' }) where the browser supports it.
• Coordinate multiple controls through a shared external store when many components need the same document-level subscription.