useFullscreen

A React hook that allows toggling between fullscreen mode and normal mode in a web application. The useFullscreen hook returns an object containing the following:

• toggleFullscreen
• exitFullscreen
• isFullscreen

Works with React 18 and 19. TypeScript types are included, and the return type is exported as UseFullscreenResult if you need to annotate it directly:

import useFullscreen, { type UseFullscreenResult } from "@toluade/use-fullscreen";

Note: When screen lock is supported, the screen stays awake when in fullscreen mode.

Install

npm

npm i @toluade/use-fullscreen --save

yarn

yarn add @toluade/use-fullscreen

react is a peer dependency, so the hook uses whichever version your app already has.

Renamed in 1.2.0

Two returned values were renamed so that the whole package spells "fullscreen" as one word, matching the Fullscreen API it wraps:

| Old | New | Status | | ------------------ | ------------------ | -------------------------------- | | toggleFullScreen | toggleFullscreen | old name deprecated, still works | | isFullScreen | isFullscreen | old name deprecated, still works | | exitFullscreen | exitFullscreen | unchanged |

Nothing breaks in 1.2.0. The old names are still returned and still work; they are marked @deprecated, so TypeScript and most editors will strike them through and point you at the replacement. They will be removed in 2.0.0.

- const { toggleFullScreen, isFullScreen } = useFullscreen(containerId);
+ const { toggleFullscreen, isFullscreen } = useFullscreen(containerId);

The hook is a default export, so whatever you named it at the import site keeps working either way.

Props

| Prop | Description | Type | | ----------- | ---------------------------------------------------------- | ------ | | containerId | The id of the element to be set to fullscreen. Required. | string |

toggleFullscreen

const { toggleFullscreen } = useFullscreen(containerId);

• toggleFullscreen(e?: MouseEvent | null) => void
  • This function toggles the element whose id is passed to the useFullscreen hook between fullscreen mode and normal mode. When an event is passed, its propagation is stopped.

exitFullscreen

const { exitFullscreen } = useFullscreen(containerId);

• exitFullscreen() => void
  • This function exits fullscreen mode.

isFullscreen

const { isFullscreen } = useFullscreen(containerId);

• isFullscreen: boolean
  • Returns true when in fullscreen mode and false when in normal mode.
  • This tracks the browser's actual fullscreen state, so it also updates when the user leaves fullscreen without your UI — by pressing Esc, for example.

Example Usage

import useFullscreen from "@toluade/use-fullscreen";

const containerId = "container";

function App() {
  const { toggleFullscreen, isFullscreen, exitFullscreen } =
    useFullscreen(containerId);

  return (
    <div id={containerId}>
      <button onClick={toggleFullscreen}>Toggle Fullscreen</button>
      {isFullscreen ? <p>Fullscreen mode</p> : <p>Normal mode</p>}
      <button onClick={exitFullscreen}>Exit Fullscreen</button>
    </div>
  );
}

import useFullscreen from "@toluade/use-fullscreen";

const containerId = "container";

function App() {
  const { toggleFullscreen, isFullscreen } = useFullscreen(containerId);

  return (
    <div id={containerId} onDoubleClick={(e) => toggleFullscreen(e)}>
      <p>{isFullscreen ? "Fullscreen Mode" : "Normal mode"}</p>
    </div>
  );
}

Troubleshooting

Nothing happens when I call toggleFullscreen.

Browsers only grant fullscreen from a user gesture, so call it from an event handler such as onClick or onDoubleClick — not from an effect or a timeout.

Nothing happens inside an iframe.

Permissions Policy blocks fullscreen in an iframe unless the parent sets allow="fullscreen". This is why embedded sandbox previews — CodeSandbox, StackBlitz and similar — refuse the request; open the preview in its own tab to test. The hook absorbs the refusal instead of throwing, so isFullscreen just stays false.

isFullscreen stays false.

Check that an element with the containerId you passed is actually in the document when the hook runs. If no element matches, the request is skipped silently.

License

MIT © Toluade