PanZoomCanvas Composition

An interactive viewport for spatial content. It owns pan and zoom input, not the meaning or layout of the content placed inside it.

Usage

Product ideaDecision note

Interaction contract

The viewport is one named keyboard region. Arrow keys pan, plus and minus zoom, and 0 or Home reset the view. Pointer drag pans; two-pointer pinch zooms; Ctrl/Command + wheel zooms. Interactive children retain their own focus and activation behavior, so dragging never replaces a node link or button.

A canvas is usually laid out inside a page column narrower than the content it holds, so the toolbar offers fullscreen alongside zoom and reset. It uses the browser's Fullscreen API rather than an overlay of its own: the browser promotes the element above every stacking context, keeps focus inside it, and closes it on Escape, so this component implements no dismissal, focus trap, or z-index of its own. Where the API is unavailable — iOS Safari among them — the control is not rendered at all rather than offered and inert.

There is still no dismissal, selection, or graph layout in this component. Reduced motion removes transform transitions while preserving every direct pan and zoom result.

Use it when spatial position is meaningful and readers need to inspect beyond the initial frame.

Don't

Use it as a substitute for a linear list, or put product-specific graph semantics into the canvas.

Loading

PanZoomCanvas.Skeleton preserves the viewport and toolbar geometry while spatial content loads.

Props

Prop	Type	Default	Notes
label	string	—	Accessible name for the keyboard-operable viewport.
children	ReactNode	—	Spatial content whose layout and semantics stay with the caller.
hint	string	—	Optional visible gesture and keyboard guidance.
zoomInLabel	string	Zoom in	Localised name for the zoom-in control.
zoomOutLabel	string	Zoom out	Localised name for the zoom-out control.
resetLabel	string	Reset canvas	Localised name for the reset control.
zoomStatusLabel	string	Canvas zoom	Localised name for the current zoom output.
fullscreenLabel	string	Enter fullscreen	Localised name for the fullscreen control. The control is absent where the browser has no Fullscreen API.
exitFullscreenLabel	string	Exit fullscreen	Localised name the same control takes while the canvas is fullscreen.
motion	boolean	true	Disables transform transitions without disabling direct manipulation.

Keyboard

Key	Result
Arrow keys	Pan one tokenized step
`+` / `=`	Zoom in
`-`	Zoom out
`0` / `Home`	Reset pan and zoom
`Escape`	Leave fullscreen, handled by the browser

Tokens

--cb-bg-subtle, --cb-surface, --cb-border, --cb-fg-*, --cb-space-*, --cb-radius-*, --cb-control-height-*, --cb-focus-*, --cb-duration-*, and --cb-ease-*.