UtilityBeginnerSSR-safehooks/utility/useFullscreen.ts

useFullscreen

Enter/exit fullscreen.

Import

TypeScript
import { useFullscreen } from '@/hooks';

API

Signature

useFullscreen(target?) → { isFullscreen, enter, exit, toggle }

When to use

Use useFullscreen instead of re-implementing the same pattern in multiple components.

SSR / Next.js

Browser utilities are SSR-gated; lifecycle hooks are safe.

Live playground

Edit the example and see it run against the real @/hooks package in this app.

Live playgroundEdit · run with real @/hooks · useFullscreen
Editor
function Stage() {
  const ref = useRef<HTMLDivElement>(null);
  const fs = useFullscreen(ref);
  return (
    <div ref={ref}>
      <button onClick={() => void fs.toggle()}>
        {fs.isFullscreen ? 'Exit' : 'Fullscreen'}
      </button>
    </div>
  );
}
Preview

Implementation source

Full library source for useFullscreen — copy into your project when you are not installing a package yet.

hooks/utility/useFullscreen.ts
import { useCallback, useEffect, useState } from 'react';
import { getTargetElement, type BasicTarget } from './getTargetElement';
import { isBrowser } from './isBrowser';
import { useLatest } from './useLatest';

export interface UseFullscreenReturn {
  isFullscreen: boolean;
  enter: () => Promise<void>;
  exit: () => Promise<void>;
  toggle: () => Promise<void>;
  isSupported: boolean;
}

/** Fullscreen API integration for an element or the document element. */
export function useFullscreen(
  target?: BasicTarget<Element>,
): UseFullscreenReturn {
  const [isFullscreen, setIsFullscreen] = useState(false);
  const targetRef = useLatest(target);
  const isSupported =
    isBrowser() &&
    typeof document !== 'undefined' &&
    !!document.fullscreenEnabled;

  const getEl = useCallback((): Element | undefined => {
    return (
      getTargetElement(targetRef.current) ??
      (isBrowser() ? document.documentElement : undefined)
    );
  }, [targetRef]);

  const enter = useCallback(async () => {
    const el = getEl();
    if (!el || !el.requestFullscreen) return;
    await el.requestFullscreen();
  }, [getEl]);

  const exit = useCallback(async () => {
    if (!isBrowser() || !document.fullscreenElement) return;
    await document.exitFullscreen();
  }, []);

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

  useEffect(() => {
    if (!isBrowser()) return;
    const onChange = () => {
      setIsFullscreen(!!document.fullscreenElement);
    };
    document.addEventListener('fullscreenchange', onChange);
    onChange();
    return () => document.removeEventListener('fullscreenchange', onChange);
  }, []);

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

Copy-paste example

useFullscreen.example.tsx
'use client';

import { useRef } from 'react';
import { useFullscreen } from '@/hooks';

export function Stage() {
  const ref = useRef<HTMLDivElement>(null);
  const fs = useFullscreen(ref);
  return (
    <div ref={ref}>
      <button onClick={() => void fs.toggle()}>
        {fs.isFullscreen ? 'Exit' : 'Fullscreen'}
      </button>
    </div>
  );
}

Production checklist

  • Called only from Client Components or other custom hooks
  • Type parameters filled in (e.g. useFetch<User[]>)
  • Tip: Lifecycle hooks are for side effects only — not for deriving render state.
  • Source of truth: open hooks/utility/useFullscreen.ts for implementation details