useFullscreen

dom

Installation

npx usehooks-cli@latest add use-fullscreen

Description

A hook for managing fullscreen mode using the Fullscreen API. Provides cross-browser support for entering and exiting fullscreen mode with callback options.

Parameters

Name	Type	Default	Description
targetRef?	React.RefObject<Element>	-	Reference to the element to make fullscreen (defaults to document.documentElement)
options?	UseFullscreenOptions	-	Configuration options for fullscreen behavior

Parameter Properties

options properties:

Name	Type	Description
onEnter?	() => void	Callback fired when entering fullscreen mode
onExit?	() => void	Callback fired when exiting fullscreen mode
onError?	(error: Error) => void	Callback fired when fullscreen operation fails

Return Type

UseFullscreenReturn

Property	Type	Description
isFullscreen	boolean	Whether currently in fullscreen mode
isSupported	boolean	Whether the Fullscreen API is supported
enter	(element?: Element) => Promise<void>	Enter fullscreen mode for the specified element
exit	() => Promise<void>	Exit fullscreen mode
toggle	(element?: Element) => Promise<void>	Toggle fullscreen mode
element	Element \| null	The current fullscreen element

Examples

Basic Fullscreen Toggle

Simple fullscreen toggle for the entire page

import { useFullscreen } from '@usehooks/use-fullscreen';

function FullscreenDemo() {
  const {
    isFullscreen,
    isSupported,
    enter,
    exit,
    toggle
  } = useFullscreen();

  if (!isSupported) {
    return <div>Fullscreen not supported</div>;
  }

  return (
    <div style={{ padding: '20px' }}>
      <h2>Fullscreen Demo</h2>
      <p>Status: {isFullscreen ? 'Fullscreen' : 'Normal'}</p>
      
      <div>
        <button onClick={() => enter()}>Enter Fullscreen</button>
        <button onClick={() => exit()}>Exit Fullscreen</button>
        <button onClick={() => toggle()}>Toggle Fullscreen</button>
      </div>
      
      {isFullscreen && (
        <div style={{
          position: 'fixed',
          top: 0,
          left: 0,
          right: 0,
          bottom: 0,
          backgroundColor: 'black',
          color: 'white',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          flexDirection: 'column'
        }}>
          <h1>Fullscreen Mode</h1>
          <button onClick={() => exit()}>Exit Fullscreen</button>
        </div>
      )}
    </div>
  );
}

Element-specific Fullscreen

Make a specific element fullscreen with ref

import { useFullscreen } from '@usehooks/use-fullscreen';
import { useRef } from 'react';

function VideoPlayer() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const {
    isFullscreen,
    enter,
    exit,
    toggle
  } = useFullscreen(videoRef, {
    onEnter: () => console.log('Video entered fullscreen'),
    onExit: () => console.log('Video exited fullscreen'),
    onError: (error) => console.error('Fullscreen error:', error)
  });

  return (
    <div>
      <video
        ref={videoRef}
        width="400"
        height="300"
        controls
        style={{
          border: isFullscreen ? 'none' : '2px solid #ccc',
          backgroundColor: 'black'
        }}
      >
        <source src="/sample-video.mp4" type="video/mp4" />
        Your browser does not support the video tag.
      </video>
      
      <div style={{ marginTop: '10px' }}>
        <button onClick={() => toggle()}>
          {isFullscreen ? 'Exit' : 'Enter'} Fullscreen
        </button>
        <p>Video is {isFullscreen ? 'fullscreen' : 'normal'}</p>
      </div>
    </div>
  );
}

Image Gallery Fullscreen

Fullscreen image viewer with navigation

import { useFullscreen } from '@usehooks/use-fullscreen';
import { useRef, useState } from 'react';

function ImageGallery() {
  const imageRef = useRef<HTMLDivElement>(null);
  const [currentImage, setCurrentImage] = useState(0);
  const {
    isFullscreen,
    enter,
    exit
  } = useFullscreen(imageRef);

  const images = [
    '/image1.jpg',
    '/image2.jpg',
    '/image3.jpg'
  ];

  const nextImage = () => {
    setCurrentImage((prev) => (prev + 1) % images.length);
  };

  const prevImage = () => {
    setCurrentImage((prev) => (prev - 1 + images.length) % images.length);
  };

  const handleImageClick = () => {
    if (!isFullscreen) {
      enter();
    }
  };

  return (
    <div>
      <div
        ref={imageRef}
        style={{
          position: 'relative',
          width: isFullscreen ? '100vw' : '400px',
          height: isFullscreen ? '100vh' : '300px',
          backgroundColor: 'black',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          cursor: isFullscreen ? 'default' : 'pointer'
        }}
        onClick={handleImageClick}
      >
        <img
          src={images[currentImage]}
          alt={`Image ${currentImage + 1}`}
          style={{
            maxWidth: '100%',
            maxHeight: '100%',
            objectFit: 'contain'
          }}
        />
        
        {isFullscreen && (
          <>
            <button
              onClick={(e) => {
                e.stopPropagation();
                prevImage();
              }}
              style={{
                position: 'absolute',
                left: '20px',
                top: '50%',
                transform: 'translateY(-50%)',
                fontSize: '24px',
                padding: '10px'
              }}
            >
              ←
            </button>
            
            <button
              onClick={(e) => {
                e.stopPropagation();
                nextImage();
              }}
              style={{
                position: 'absolute',
                right: '20px',
                top: '50%',
                transform: 'translateY(-50%)',
                fontSize: '24px',
                padding: '10px'
              }}
            >
              →
            </button>
            
            <button
              onClick={(e) => {
                e.stopPropagation();
                exit();
              }}
              style={{
                position: 'absolute',
                top: '20px',
                right: '20px',
                fontSize: '18px',
                padding: '10px'
              }}
            >
              ✕
            </button>
          </>
        )}
      </div>
      
      {!isFullscreen && (
        <div style={{ marginTop: '10px' }}>
          <button onClick={prevImage}>Previous</button>
          <span style={{ margin: '0 10px' }}>
            {currentImage + 1} of {images.length}
          </span>
          <button onClick={nextImage}>Next</button>
          <p>Click image to view fullscreen</p>
        </div>
      )}
    </div>
  );
}

Dependencies

react

Notes

•Requires user gesture to enter fullscreen mode
•Cross-browser support for webkit, moz, and ms prefixes
•Automatically handles fullscreen change events
•Cleans up event listeners on component unmount
•Some browsers may have restrictions on which elements can be fullscreen
•Fullscreen mode may be blocked by browser settings or extensions

Implementation

'use client';

import { useState, useEffect, useCallback, useRef } from "react";

export interface UseFullscreenOptions {
  onEnter?: () => void;
  onExit?: () => void;
  onError?: (error: Error) => void;
}

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

export function useFullscreen(
  targetRef?: React.RefObject<Element>,
  options: UseFullscreenOptions = {}
): UseFullscreenReturn {
  const [isFullscreen, setIsFullscreen] = useState(false);
  const [element, setElement] = useState<Element | null>(null);
  const optionsRef = useRef(options);

  // Update options ref when options change
  useEffect(() => {
    optionsRef.current = options;
  }, [options]);

  // Check if fullscreen is supported
  const isSupported = Boolean(
    document.fullscreenEnabled ||
      (document as any).webkitFullscreenEnabled ||
      (document as any).mozFullScreenEnabled ||
      (document as any).msFullscreenEnabled
  );

  // Handle fullscreen change events
  useEffect(() => {
    const handleFullscreenChange = () => {
      const fullscreenElement =
        document.fullscreenElement ||
        (document as any).webkitFullscreenElement ||
        (document as any).mozFullScreenElement ||
        (document as any).msFullscreenElement;

      const isCurrentlyFullscreen = Boolean(fullscreenElement);
      setIsFullscreen(isCurrentlyFullscreen);
      setElement(fullscreenElement);

      if (isCurrentlyFullscreen) {
        optionsRef.current.onEnter?.();
      } else {
        optionsRef.current.onExit?.();
      }
    };

    const handleFullscreenError = () => {
      optionsRef.current.onError?.(
        new Error("Failed to enter fullscreen mode")
      );
    };

    // Add event listeners for different browsers
    document.addEventListener("fullscreenchange", handleFullscreenChange);
    document.addEventListener("webkitfullscreenchange", handleFullscreenChange);
    document.addEventListener("mozfullscreenchange", handleFullscreenChange);
    document.addEventListener("MSFullscreenChange", handleFullscreenChange);

    document.addEventListener("fullscreenerror", handleFullscreenError);
    document.addEventListener("webkitfullscreenerror", handleFullscreenError);
    document.addEventListener("mozfullscreenerror", handleFullscreenError);
    document.addEventListener("MSFullscreenError", handleFullscreenError);

    // Set initial state
    handleFullscreenChange();

    return () => {
      document.removeEventListener("fullscreenchange", handleFullscreenChange);
      document.removeEventListener(
        "webkitfullscreenchange",
        handleFullscreenChange
      );
      document.removeEventListener(
        "mozfullscreenchange",
        handleFullscreenChange
      );
      document.removeEventListener(
        "MSFullscreenChange",
        handleFullscreenChange
      );

      document.removeEventListener("fullscreenerror", handleFullscreenError);
      document.removeEventListener(
        "webkitfullscreenerror",
        handleFullscreenError
      );
      document.removeEventListener("mozfullscreenerror", handleFullscreenError);
      document.removeEventListener("MSFullscreenError", handleFullscreenError);
    };
  }, []);

  const enter = useCallback(
    async (elementToFullscreen?: Element) => {
      if (!isSupported) {
        throw new Error("Fullscreen API is not supported");
      }

      const target =
        elementToFullscreen || targetRef?.current || document.documentElement;

      if (!target) {
        throw new Error("No element provided for fullscreen");
      }

      try {
        if (target.requestFullscreen) {
          await target.requestFullscreen();
        } else if ((target as any).webkitRequestFullscreen) {
          await (target as any).webkitRequestFullscreen();
        } else if ((target as any).mozRequestFullScreen) {
          await (target as any).mozRequestFullScreen();
        } else if ((target as any).msRequestFullscreen) {
          await (target as any).msRequestFullscreen();
        } else {
          throw new Error("Fullscreen API is not supported");
        }
      } catch (error) {
        optionsRef.current.onError?.(error as Error);
        throw error;
      }
    },
    [isSupported, targetRef]
  );

  const exit = useCallback(async () => {
    if (!isSupported) {
      throw new Error("Fullscreen API is not supported");
    }

    try {
      if (document.exitFullscreen) {
        await document.exitFullscreen();
      } else if ((document as any).webkitExitFullscreen) {
        await (document as any).webkitExitFullscreen();
      } else if ((document as any).mozCancelFullScreen) {
        await (document as any).mozCancelFullScreen();
      } else if ((document as any).msExitFullscreen) {
        await (document as any).msExitFullscreen();
      } else {
        throw new Error("Fullscreen API is not supported");
      }
    } catch (error) {
      optionsRef.current.onError?.(error as Error);
      throw error;
    }
  }, [isSupported]);

  const toggle = useCallback(
    async (elementToFullscreen?: Element) => {
      if (isFullscreen) {
        await exit();
      } else {
        await enter(elementToFullscreen);
      }
    },
    [isFullscreen, enter, exit]
  );

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

useFetch

CLI Docs All Hooks

useRoleGuard