API reference | React Viewport

Runtime

useViewport()

Subscribes to the current window, or to the window supplied by the nearest ViewportProvider.

Type signature

export declare function useViewport(): ViewportState;

useViewportCssVariables()

Writes current geometry to options.target, or to the document root when target is omitted. The target can be an HTMLElement, a React ref, or null.

Type signature

export declare function useViewportCssVariables(options?: ViewportCssVariablesOptions): void;

<ViewportProvider>

Renders children and scopes descendants to targetWindow. Omitting targetWindow uses the global window; passing null intentionally selects the server snapshot.

Type signature

export declare function ViewportProvider({ children, targetWindow, }: ViewportProviderProps): React.ReactNode;

Types

LayoutViewport

Type definition

export interface LayoutViewport {
  readonly width: number;
  readonly height: number;
}

VisualViewportState

Type definition

export interface VisualViewportState {
  readonly width: number;
  readonly height: number;
  readonly offsetTop: number;
  readonly offsetLeft: number;
  readonly pageTop: number;
  readonly pageLeft: number;
  readonly scale: number;
}

KeyboardState

Type definition

export interface KeyboardState {
  readonly open: boolean;
  readonly height: number;
}

SafeAreaInsets

Type definition

export interface SafeAreaInsets {
  readonly top: number;
  readonly right: number;
  readonly bottom: number;
  readonly left: number;
}

ViewportOrientation

Type definition

export type ViewportOrientation = 'portrait' | 'landscape';

ViewportSupport

Type definition

export interface ViewportSupport {
  readonly visualViewport: boolean;
  readonly virtualKeyboard: boolean;
}

ViewportState

Type definition

export interface ViewportState {
  readonly ready: boolean;
  readonly layout: LayoutViewport | null;
  readonly visual: VisualViewportState | null;
  readonly keyboard: KeyboardState;
  readonly safeArea: SafeAreaInsets;
  readonly orientation: ViewportOrientation | null;
  readonly supported: ViewportSupport;
}

ViewportProviderProps

Type definition

export interface ViewportProviderProps {
  readonly children: React.ReactNode;
  readonly targetWindow?: Window | null;
}

ViewportCssVariablesOptions

Type definition

export interface ViewportCssVariablesOptions {
  readonly target?: HTMLElement | React.RefObject<HTMLElement | null> | null;
}

CSS variables

Lengths serialize as CSS pixels; scale is unitless. Dimensional values are absent until the first client measurement.

--react-viewport-layout-width
--react-viewport-layout-height
--react-viewport-visual-width
--react-viewport-visual-height
--react-viewport-visual-offset-top
--react-viewport-visual-offset-left
--react-viewport-visual-page-top
--react-viewport-visual-page-left
--react-viewport-scale
--react-viewport-keyboard-height
--react-viewport-safe-area-top
--react-viewport-safe-area-right
--react-viewport-safe-area-bottom
--react-viewport-safe-area-left