use-fullscreen

Enter, exit, and observe fullscreen for an element.


Package	`@vizejs/composable/use-fullscreen`
Own the source	`vize lib pull composable:use-fullscreen`
Runtime exports	`useFullscreen`
Gzip budget	2048 B

Usage

import { useFullscreen } from "@vizejs/composable/use-fullscreen";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useFullscreen`	system	experimental	deterministic-fallback	caller-managed	reactive-scope	web, desktop	`window`	`tryOnScopeDispose`

API

`useFullscreen`

Enter, exit, and observe fullscreen for an element. Supports the standard Fullscreen API and the WebKit-prefixed variant. isFullscreen is true only while this target is the fullscreen element and follows fullscreenchange, so pressing Escape is reflected. Listeners are removed when the owning scope stops; with autoExit the target also leaves fullscreen then. Server rendering: supported and isFullscreen are false and nothing is requested.

function useFullscreen( target?: MaybeRefOrGetter<FullscreenElementLike | null | undefined>, options: UseFullscreenOptions = {}, ): FullscreenControls

const player = useTemplateRef<HTMLElement>("player");
const { toggle, isFullscreen } = useFullscreen(player);

Types

`FullscreenElementLike`

Element that can enter fullscreen (standard or WebKit-prefixed).

Member	Type	Description
`requestFullscreen`?	`(options?: { navigationUI?: FullscreenNavigationUI }) => Promise<void>`	Standard request.
`webkitRequestFullscreen`?	`() => void`	Legacy WebKit request (Safari < 16.4).

`FullscreenHost`

Document-level fullscreen capability (standard or WebKit-prefixed).

Member	Type	Description
`fullscreenElement`?	`unknown`	Element currently in fullscreen.
`webkitFullscreenElement`?	`unknown`	Legacy WebKit fullscreen element.
`fullscreenEnabled`?	`boolean`	Whether fullscreen is allowed (for example by permissions policy).
`webkitFullscreenEnabled`?	`boolean`	Legacy WebKit flag.
`exitFullscreen`?	`() => Promise<void>`	Standard exit.
`webkitExitFullscreen`?	`() => void`	Legacy WebKit exit.
`documentElement`?	`FullscreenElementLike \| null`	Default fullscreen target.

`UseFullscreenOptions`

Options for useFullscreen.

Member	Type	Description
`host`?	`MaybeRefOrGetter<FullscreenHost \| null \| undefined>`	Document capability for alternate runtimes and tests.
`autoExit`?	`boolean`	Exit fullscreen when the owning reactive scope stops while this composable's target is fullscreen.
`navigationUI`?	`FullscreenNavigationUI`	Navigation UI preference passed to `requestFullscreen`.

`FullscreenControls`

Reactive state and actions returned by useFullscreen.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether fullscreen can be requested.
`isFullscreen`	`Readonly<Ref<boolean>>`	Whether this composable's target is the current fullscreen element.
`enter`	`() => Promise<boolean>`	Enter fullscreen. Browsers require a user gesture.
`exit`	`() => Promise<boolean>`	Exit fullscreen when this composable's target owns it.
`toggle`	`() => Promise<boolean>`	Toggle fullscreen.