use-fullscreen (use-fullscreen)

Enter and exit fullscreen mode for a given element or the entire page.

v0.1.0

Usage

import { use-fullscreen } from "@/hooks"

"use client";

import React, { useRef } from "react";

import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";

import { useFullscreen } from "@/components/hooks/use-fullscreen";

export function UseFullscreenDemo() {
  const boxRef = useRef<HTMLDivElement>(null);
  const [isFullscreen, enter, exit] = useFullscreen(
    boxRef as React.RefObject<HTMLElement>
  );

  return (
    <Card className="relative max-w-md w-full">
      <CardHeader>
        <CardTitle>useFullscreen</CardTitle>
        <CardDescription>
          This component uses the <code>useFullscreen</code> hook to toggle
          fullscreen mode for a specific element.
        </CardDescription>
      </CardHeader>
      <CardContent>
        <p className="text-lg font-semibold text-primary">
          {isFullscreen ? "In Fullscreen" : "Not Fullscreen"}
        </p>
      </CardContent>
      <CardFooter className="flex gap-2">
        <Button onClick={enter} disabled={isFullscreen} variant="secondary">
          Enter Fullscreen
        </Button>
        <Button onClick={exit} disabled={!isFullscreen} variant="destructive">
          Exit Fullscreen
        </Button>
      </CardFooter>
    </Card>
  );
}

Install

npx wkkkis-hooks add use-fullscreen

Options

Name	Type	Default	Description
ref	RefObject<HTMLElement> \| null	null	The ref of the element to enter/exit fullscreen. If null, uses the document.

Returns — Properties

Name	Type	Default	Description
Returns a tuple	—	—	[isFullscreen, enter, exit] .
isFullscreen	—	—	is true if the element (or page) is in fullscreen.
enter	—	—	and exit are functions to enter/exit fullscreen mode.

Cross-Browser Support

The hook uses the appropriate vendor-prefixed Fullscreen API methods for compatibility with all major browsers.
Listeners for fullscreen changes are also vendor-prefixed.

Ref Behavior

If a ref is provided, the hook will enter/exit fullscreen for that element.
If null is passed, the hook will use the entire document ( document.documentElement ).

State Updates & Event Handling

The hook tracks whether the referenced element (or the page) is currently in fullscreen.
Listens for fullscreen change events and updates state accordingly.
The state is updated immediately on mount and whenever fullscreen changes.

Returned Values

Returns a tuple: [isFullscreen, enter, exit] .
isFullscreen is true if the element (or page) is in fullscreen.
enter and exit are functions to enter/exit fullscreen mode.

Cleanup

All event listeners are removed automatically when the component unmounts.

Caveats & Best Practices

Only works in the browser (client-side). On the server, the functions are no-ops.
If the Fullscreen API is not available, the functions will be no-ops.
The element must be in the DOM and visible to enter fullscreen.
Some browsers may block fullscreen requests unless triggered by a user gesture.

Files in this hook

Source	Destination
files/use-fullscreen.ts	src/hooks/use-fullscreen.ts