use-visual-viewport

Track the visual viewport and on-screen keyboard.


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

Usage

import { useVisualViewport } from "@vizejs/composable/use-visual-viewport";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useVisualViewport`	dom	experimental	deterministic-fallback	stable	reactive-scope	web, desktop	`window`	`tryOnScopeDispose`

API

`useVisualViewport`

Track the visual viewport and on-screen keyboard. On mobile browsers the visual viewport shrinks (or scrolls) when a virtual keyboard opens while the layout viewport stays put; keyboardHeight is the occluded bottom area (innerHeight - height - offsetTop), or the VirtualKeyboard API rectangle when overlaysContent is enabled. Pin toolbars above the keyboard with bottom: calc(var(--kb, 0px)) bound to it. Server rendering reports zeros (scale 1) and attaches nothing; inside a component the host attaches after mount, so hydration renders the same zeros first. Listeners (resize, scroll, geometrychange) are passive and removed with the owning reactive scope.

function useVisualViewport(options: UseVisualViewportOptions = {}): VisualViewportControls

const { keyboardHeight, keyboardOpen } = useVisualViewport();
const toolbarStyle = computed(() => ({ bottom: `${keyboardHeight.value}px` }));

Types

`VisualViewportHost`

Structural VisualViewport observed by useVisualViewport.

Member	Type	Description
`width`	`number`	Visible width in CSS pixels.
`height`	`number`	Visible height in CSS pixels (shrinks when an on-screen keyboard overlays the page).
`offsetTop`	`number`	Offset of the visual viewport from the layout viewport's top edge.
`offsetLeft`	`number`	Offset of the visual viewport from the layout viewport's left edge.
`scale`	`number`	Pinch-zoom scale factor.

`VirtualKeyboardHost`

Structural VirtualKeyboard API (navigator.virtualKeyboard).

Member	Type	Description
`overlaysContent`	`boolean`	Whether the keyboard overlays content instead of resizing the viewport.
`boundingRect`	`{ readonly height: number }`	Keyboard rectangle in CSS pixels.

`VisualViewportWindowHost`

Window-like capability read by useVisualViewport.

Member	Type	Description
`innerHeight`	`number`	Layout viewport height.
`visualViewport`?	`VisualViewportHost \| null`	Visual viewport, when the engine supports it.
`navigator`?	`object`	Navigator that may expose the VirtualKeyboard API as `virtualKeyboard`.

`UseVisualViewportOptions`

Options for useVisualViewport.

Member	Type	Description
`keyboardThreshold`?	`number`	Minimum occluded height (CSS px) reported as an open keyboard, filtering browser toolbars that collapse while scrolling.
`overlaysContent`?	`boolean`	Opt in to `navigator.virtualKeyboard.overlaysContent = true` (Chromium) so the keyboard height comes from the VirtualKeyboard API and the layout viewport no longer resizes. The previous value is restored on cleanup.
`host`?	`MaybeRefOrGetter<VisualViewportWindowHost \| null \| undefined>`	Reactive window capability for alternate runtimes and tests.

`VisualViewportControls`

Reactive viewport geometry returned by useVisualViewport.

Member	Type	Description
`width`	`Readonly<Ref<number>>`	Visual viewport width (0 on the server).
`height`	`Readonly<Ref<number>>`	Visual viewport height (0 on the server).
`offsetTop`	`Readonly<Ref<number>>`	Visual viewport top offset within the layout viewport.
`offsetLeft`	`Readonly<Ref<number>>`	Visual viewport left offset within the layout viewport.
`scale`	`Readonly<Ref<number>>`	Pinch-zoom scale (1 on the server).
`keyboardHeight`	`Readonly<Ref<number>>`	Height of the bottom area hidden by an on-screen keyboard, in CSS px.
`keyboardOpen`	`ComputedRef<boolean>`	Whether `keyboardHeight` exceeds `keyboardThreshold`.
`isSupported`	`Readonly<Ref<boolean>>`	Whether a VisualViewport (or VirtualKeyboard) capability is attached.