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 · useFullscreenEditor
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.tsfor implementation details