8
Hooks

useFullscreen

A hook for controlling browser fullscreen mode with cross-browser support and iOS fallbacks.

useFullscreen

The useFullscreen hook provides a way to control browser fullscreen mode with cross-browser support and iOS fallbacks. It makes it easy to toggle any element to fullscreen mode, listen for fullscreen changes, and handle browser compatibility issues.

Fullscreen Demo

Content Area

This area will enter fullscreen mode

Fullscreen Status
Not Supported
Normal
Try it out

Use these buttons or press F11:

Installation

Install the useFullscreen hook using:

npx axionjs-ui add hook use-fullscreen

File Structure

use-fullscreen.ts

Parameters

PropTypeDefault
options
FullscreenOptions
{}

Return Value

PropTypeDefault
isFullscreen
boolean
-
isSupported
boolean
-
error
Error | null
-
enter
() => Promise<boolean>
-
exit
() => Promise<boolean>
-
toggle
() => Promise<boolean>
-

Examples

Video Player with Fullscreen

A common use case for fullscreen mode is in video players. This example shows how to implement a simple video player with fullscreen controls.

Video Player with Fullscreen

Video Player Demo

(Simulated content)

1:23 / 3:45

Click the expand icon or anywhere on the video to toggle fullscreen mode

Use fullscreen mode to create an immersive image gallery viewing experience.

Fullscreen Image Gallery

Click any image to view it in fullscreen mode

Presentation Mode

import { useRef, useState } from "react";
import { useFullscreen } from "@/hooks/use-fullscreen";
 
interface Slide {
  title: string;
  content: string;
}
 
function Presentation() {
  const slides: Slide[] = [
    { title: "Introduction", content: "Welcome to the presentation!" },
    { title: "Key Points", content: "Here are the important takeaways..." },
    { title: "Data Analysis", content: "Let's look at the data..." },
    { title: "Conclusion", content: "Thank you for attending!" },
  ];
  
  const [currentSlide, setCurrentSlide] = useState(0);
  const presentationRef = useRef<HTMLDivElement>(null);
  
  const { isFullscreen, toggle } = useFullscreen({
    element: presentationRef,
  });
  
  const nextSlide = () => {
    setCurrentSlide((prev) => Math.min(prev + 1, slides.length - 1));
  };
  
  const prevSlide = () => {
    setCurrentSlide((prev) => Math.max(prev - 1, 0));
  };
  
  const handleKeyDown = (e: React.KeyboardEvent) => {
    if (e.key === "ArrowRight") nextSlide();
    if (e.key === "ArrowLeft") prevSlide();
    if (e.key === "f") toggle();
  };
  
  return (
    <div 
      ref={presentationRef}
      className={`
        ${isFullscreen ? "fixed inset-0 z-50 bg-white" : "border rounded-lg"}
        flex flex-col
      `}
      tabIndex={0}
      onKeyDown={handleKeyDown}
    >
      <div className="p-4 flex justify-between items-center border-b">
        <h2>{slides[currentSlide].title}</h2>
        <div>
          <span>Slide {currentSlide + 1} of {slides.length}</span>
          <button 
            className="ml-4"
            onClick={toggle}
          >
            {isFullscreen ? "Exit Presentation" : "Present"}
          </button>
        </div>
      </div>
      
      <div className="flex-1 flex items-center justify-center p-8">
        <div className="text-xl max-w-2xl">
          {slides[currentSlide].content}
        </div>
      </div>
      
      <div className="p-4 flex justify-between border-t">
        <button 
          onClick={prevSlide}
          disabled={currentSlide === 0}
        >
          Previous
        </button>
        <button 
          onClick={nextSlide}
          disabled={currentSlide === slides.length - 1}
        >
          Next
        </button>
      </div>
    </div>
  );
}

Browser Support and Compatibility

The Fullscreen API is supported in all modern browsers, but there are some important compatibility notes:

  • iOS Safari: Doesn’t support the standard fullscreen API. The hook provides a CSS-based fallback
  • Safari: Requires webkitRequestFullscreen() and similar prefixed methods
  • Firefox: Uses mozRequestFullScreen() (note the capital ‘S’)
  • Older IE/Edge: Uses msRequestFullscreen()
  • User Interaction: Most browsers require fullscreen to be triggered by a user interaction (click, tap)

Use Cases

  • Media Players: Video and audio players
  • Image Galleries: Immersive photo viewing
  • Games: Full-screen gaming experiences
  • Presentations: Slide shows and presentations
  • Data Visualization: Interactive charts and graphs
  • Reading Mode: Distraction-free reading experiences
  • Kiosk Applications: Public-facing interactive displays

Accessibility

For accessible fullscreen implementations:

  • Ensure keyboard navigation works properly in fullscreen mode
  • Provide visible controls for exiting fullscreen
  • Support the Escape key for exiting fullscreen (this is built into most browsers)
  • Announce fullscreen state changes for screen reader users
  • Maintain focus management when entering/exiting fullscreen

Best Practices

  • Always check isSupported before attempting to use fullscreen
  • Ensure fullscreen is triggered by explicit user interaction
  • Provide clear visual feedback for fullscreen state changes
  • Include visible controls for exiting fullscreen mode
  • When possible, target specific containers rather than the entire document
  • Test on multiple browsers and devices, especially iOS
  • Be aware that fullscreen requests may be rejected by browsers in certain conditions

On this page