useZoomPinch

Lightweight React hook for pan, pinch-to-zoom, rotation, and scroll zoom with trackpad and touch support. Zero dependencies beyond React.

Live Demo

Features

Scroll to pan — mouse wheel and trackpad two-finger scroll
Pinch to zoom — trackpad pinch (via ctrlKey + wheel) and multi-touch pinch on mobile
Pointer drag — mouse drag and single-touch drag for panning
Rotation — two-finger rotation with rotateTo/rotateBy methods
Gesture toggles — enable/disable pan, zoom, and rotate independently
Double-tap zoom — configurable toggle/zoomIn/reset modes
Inertia — momentum-based pan with configurable friction
Animated transitions — smooth easing for programmatic view changes
Bounds — constrain panning within rectangular limits
Keyboard navigation — arrow keys, +/-, rotation with [ / ]
Coordinate conversion — screenToContent / contentToScreen
Zoom snap levels — snap to predefined zoom levels on gesture end
Snap to grid — snap positions to a grid (continuous or on end)
Auto-fit content — fitToContent with ResizeObserver auto-resize
Configurable pan button — left, middle, or right mouse button
Bounce at bounds — rubber-band overscroll with snap-back animation
Axis locking — restrict pan to horizontal or vertical only
Cursor management — automatic grab/grabbing cursor on drag
Wheel mode — swap default: wheel zooms, ctrl+wheel pans
Rotation constraints — min/max angle and rotation snap levels
Activation keys — require Shift/Alt/Ctrl for specific gestures
onTransformEnd — unified callback after any gesture ends
Navigation — panTo, panBy, zoomTo, fitToRect for precise viewport control
Controlled & uncontrolled modes
Granular events — onPanStart/End, onZoomStart/End, onPinchStart/End, onRotateStart/End
Event filtering — shouldHandleEvent to exclude interactive elements
Stable listeners — config changes don't re-register event listeners
TypeScript-first with full type exports
Tree-shakeable ESM + CJS dual build
~5.2 KB minified + gzipped

Installation

npm install use-zoom-pinch

Quick Start

import { useRef } from "react"
import { useZoomPinch } from "use-zoom-pinch"

function Canvas() {
  const containerRef = useRef<HTMLDivElement>(null)
  const { view } = useZoomPinch({ containerRef })

  return (
    <div
      ref={containerRef}
      style={{ width: "100%", height: "100vh", overflow: "hidden", touchAction: "none" }}
    >
      <div
        style={{
          transform: `translate(${view.x}px, ${view.y}px) scale(${view.zoom})`,
          transformOrigin: "0 0",
        }}
      >
        {/* Your zoomable content here */}
      </div>
    </div>
  )
}

Controlled Mode

import { useRef, useState } from "react"
import { useZoomPinch, type ViewState } from "use-zoom-pinch"

function ControlledCanvas() {
  const containerRef = useRef<HTMLDivElement>(null)
  const [viewState, setViewState] = useState<ViewState>({ x: 0, y: 0, zoom: 1 })

  const { view, zoomIn, zoomOut, resetView } = useZoomPinch({
    containerRef,
    viewState,
    onViewStateChange: setViewState,
  })

  return (
    <div>
      <button onClick={() => zoomIn(1.5, { animate: true })}>Zoom In</button>
      <button onClick={() => zoomOut(1.5, { animate: true })}>Zoom Out</button>
      <button onClick={() => resetView({ animate: true })}>Reset</button>

      <div
        ref={containerRef}
        style={{ width: "100%", height: "100vh", overflow: "hidden", touchAction: "none" }}
      >
        <div
          style={{
            transform: `translate(${view.x}px, ${view.y}px) scale(${view.zoom})`,
            transformOrigin: "0 0",
          }}
        >
          {/* Your content */}
        </div>
      </div>
    </div>
  )
}

Animated Transitions

All programmatic methods accept an optional AnimationOptions parameter:

const {
  setView,
  centerZoom,
  resetView,
  zoomIn,
  zoomOut,
  zoomToElement,
  panTo,
  panBy,
  zoomTo,
  fitToRect,
} = useZoomPinch({
  containerRef,
})

// Instant (default, backward-compatible)
setView({ x: 100, y: 200, zoom: 2 })

// Animated
setView({ x: 100, y: 200, zoom: 2 }, { animate: true, duration: 300 })

// With custom easing
import { easeInOut } from "use-zoom-pinch"
resetView({ animate: true, duration: 500, easing: easeInOut })

// Zoom to a specific element
const elRef = useRef<HTMLDivElement>(null)
zoomToElement(elRef.current!, 2, { animate: true })

Built-in Easings

linear — constant speed
easeOut — fast start, slow end (default)
easeInOut — slow start, fast middle, slow end

Navigation

const { panTo, panBy, zoomTo, fitToRect } = useZoomPinch({ containerRef })

// Center on a point in content space
panTo(500, 300, { animate: true })

// Shift viewport by 100px right, 50px down
panBy(100, 50)

// Zoom to 3x centered on a content-space point
zoomTo(3, { x: 500, y: 300 }, { animate: true })

// Fit a region into view with padding
fitToRect({ x: 100, y: 100, width: 400, height: 300 }, { animate: true, padding: 20 })

Rotation

Two-finger rotation is detected during pinch gestures. Disabled by default — enable via gestures:

const { view, rotateTo, rotateBy } = useZoomPinch({
  containerRef,
  gestures: { rotate: true },
})

// Apply with CSS:
// transform: `translate(${view.x}px, ${view.y}px) scale(${view.zoom}) rotate(${view.rotation ?? 0}deg)`

// Programmatic rotation
rotateTo(45, { animate: true })
rotateBy(90, { animate: true })

Gesture Toggles

Enable or disable individual gesture types:

// Only zoom, no pan or rotate
useZoomPinch({ containerRef, gestures: { pan: false, zoom: true, rotate: false } })

// Only rotate (e.g. image rotation tool)
useZoomPinch({ containerRef, gestures: { pan: false, zoom: false, rotate: true } })

// All gestures (pan + zoom + rotate)
useZoomPinch({ containerRef, gestures: { rotate: true } })

Imperative methods (setView, panTo, rotateTo, etc.) always work regardless of gesture toggles.

Double-Tap Zoom

Double-tap (or double-click) zooms to the tap point. Enabled by default in toggle mode.

// Default: toggle between 1x and 2x zoom
useZoomPinch({ containerRef })

// Customize behavior
useZoomPinch({
  containerRef,
  doubleTap: { mode: "zoomIn", step: 3 }, // always zoom in by 3x
})

// Disable double-tap
useZoomPinch({ containerRef, doubleTap: false })

Modes

"toggle" (default) — zoom in if at 1x, reset if zoomed in
"zoomIn" — always zoom in by step
"reset" — always reset to { x: 0, y: 0, zoom: 1 }

Inertia

Pan with momentum after releasing the pointer. Enabled by default.

// Default: friction 0.92
useZoomPinch({ containerRef })

// Custom friction (lower = more friction, faster stop)
useZoomPinch({ containerRef, inertia: { friction: 0.85 } })

// Disable inertia
useZoomPinch({ containerRef, inertia: false })

Event Filtering

Exclude interactive elements (buttons, inputs) from gesture handling:

useZoomPinch({
  containerRef,
  shouldHandleEvent: (e) => !(e.target as HTMLElement).closest(".no-pan"),
})

Granular Events

useZoomPinch({
  containerRef,
  onPanStart: (view) => console.log("Pan started", view),
  onPanEnd: (view) => console.log("Pan ended", view),
  onZoomStart: (view) => console.log("Zoom started", view),
  onZoomEnd: (view) => console.log("Zoom ended", view),
  onPinchStart: (view) => console.log("Pinch started", view),
  onPinchEnd: (view) => console.log("Pinch ended", view),
  onRotateStart: (view) => console.log("Rotate started", view),
  onRotateEnd: (view) => console.log("Rotate ended", view),
})

Bounds

Constrain panning within rectangular limits:

useZoomPinch({
  containerRef,
  bounds: { minX: -500, maxX: 500, minY: -300, maxY: 300 },
})

Keyboard Navigation

Enable keyboard controls with arrow keys, zoom (+/-), reset (0), and rotation ([ / ]):

// Enable with defaults (panStep: 50, zoomStep: 1.5, rotateStep: 15)
useZoomPinch({ containerRef, keyboard: true })

// Custom steps
useZoomPinch({
  containerRef,
  keyboard: { enabled: true, panStep: 100, zoomStep: 2 },
})

Coordinate Conversion

Convert between screen and content coordinates:

const { screenToContent, contentToScreen } = useZoomPinch({ containerRef })

// Map a click to content space
const handleClick = (e: MouseEvent) => {
  const pos = screenToContent(e.clientX, e.clientY)
  console.log("Clicked at content position:", pos)
}

// Position a tooltip over content
const screenPos = contentToScreen(itemX, itemY)

Zoom Snap Levels

Snap zoom to predefined levels on gesture end:

useZoomPinch({
  containerRef,
  zoomSnapLevels: [0.5, 1, 2, 4],
})

Snap to Grid

Snap pan position to a grid:

// Snap on gesture end (with animation)
useZoomPinch({ containerRef, snapToGrid: { size: 50 } })

// Snap continuously during gestures
useZoomPinch({ containerRef, snapToGrid: { size: 50, mode: "always" } })

Fit to Content

Auto-fit content to container on mount and resize:

const { fitToContent } = useZoomPinch({
  containerRef,
  contentRect: { width: 1920, height: 1080 }, // auto-fits on mount + resize
})

// Manual fit with padding
fitToContent({ animate: true, padding: 20 })

Pan Button

Configure which mouse button triggers panning:

// Use middle mouse button for pan (frees left click for selection)
useZoomPinch({ containerRef, panButton: 1 })

API

`useZoomPinch(options)`

Options

Option	Type	Default	Description
`containerRef`	`RefObject<HTMLElement \| null>`	required	Ref to the container element
`minScale`	`number`	`0.1`	Minimum zoom level
`maxScale`	`number`	`50`	Maximum zoom level
`panSpeed`	`number`	`1`	Pan speed multiplier (mouse wheel)
`zoomSpeed`	`number`	`1`	Zoom speed multiplier (mouse wheel)
`initialViewState`	`ViewState`	`{ x: 0, y: 0, zoom: 1 }`	Initial view for uncontrolled mode
`viewState`	`ViewState`	—	Controlled view state
`onViewStateChange`	`(view: ViewState) => void`	—	Callback on view change
`enabled`	`boolean`	`true`	Enable/disable gesture handling
`gestures`	`GesturesOptions`	`{ pan: true, zoom: true, rotate: false }`	Toggle individual gesture types
`panButton`	`0 \| 1 \| 2`	`0`	Mouse button for pan (0=left, 1=middle, 2=right)
`bounds`	`BoundsOptions`	—	Constrain panning within bounds
`keyboard`	`KeyboardOptions \| boolean`	`false`	Keyboard navigation (pass `true` for defaults)
`zoomSnapLevels`	`number[]`	—	Snap zoom to nearest level on gesture end
`snapToGrid`	`SnapToGridOptions \| false`	`false`	Snap position to grid
`contentRect`	`{ width; height }`	—	Content size for `fitToContent` + auto-fit
`rotation`	`RotationOptions`	—	Min/max angle and rotation snap levels
`wheelMode`	`"pan" \| "zoom"`	`"pan"`	Default wheel behavior
`cursor`	`CursorOptions \| false`	enabled	Auto cursor (grab/grabbing). `false` to disable
`axis`	`"x" \| "y"`	—	Restrict gestures to a single axis
`activationKeys`	`ActivationKeyOptions`	—	Require key held for specific gestures
`shouldHandleEvent`	`(event) => boolean`	—	Filter which events are handled
`doubleTap`	`DoubleTapOptions \| false`	`{ mode: "toggle", step: 2 }`	Double-tap zoom config, or `false` to disable
`inertia`	`InertiaOptions \| false`	`{ friction: 0.92 }`	Pan inertia config, or `false` to disable
`onPanStart`	`(view: ViewState) => void`	—	Fired when drag starts
`onPanEnd`	`(view: ViewState) => void`	—	Fired when drag ends
`onZoomStart`	`(view: ViewState) => void`	—	Fired when wheel zoom starts
`onZoomEnd`	`(view: ViewState) => void`	—	Fired when wheel zoom ends (150ms debounce)
`onPinchStart`	`(view: ViewState) => void`	—	Fired when pinch starts
`onPinchEnd`	`(view: ViewState) => void`	—	Fired when pinch ends
`onRotateStart`	`(view: ViewState) => void`	—	Fired when rotation starts
`onRotateEnd`	`(view: ViewState) => void`	—	Fired when rotation ends
`onTransformEnd`	`(view: ViewState) => void`	—	Fired after any gesture ends

Returns

Property	Type	Description
`view`	`ViewState`	Current view state
`isAnimating`	`boolean`	Whether an animation is running
`setView`	`(view, options?) => void`	Imperatively set the view
`centerZoom`	`(zoom, options?) => void`	Zoom to level, centered in container
`resetView`	`(options?) => void`	Reset to `{ x: 0, y: 0, zoom: 1 }`
`zoomIn`	`(step?, options?) => void`	Zoom in by step (default 1.5x)
`zoomOut`	`(step?, options?) => void`	Zoom out by step (default 1.5x)
`zoomToElement`	`(el, scale?, options?) => void`	Zoom and center on an element
`panTo`	`(x, y, options?) => void`	Center viewport on content-space point
`panBy`	`(dx, dy, options?) => void`	Shift viewport by relative offset
`zoomTo`	`(zoom, point?, options?) => void`	Zoom to level, optionally anchored
`fitToRect`	`(rect, options?) => void`	Fit a content-space rectangle into view
`rotateTo`	`(angle, options?) => void`	Set rotation to absolute angle (degrees)
`rotateBy`	`(delta, options?) => void`	Rotate by relative delta (degrees)
`screenToContent`	`(screenX, screenY) => { x, y }`	Convert screen to content coordinates
`contentToScreen`	`(contentX, contentY) => { x, y }`	Convert content to screen coordinates
`fitToContent`	`(options?) => void`	Fit content to container (needs `contentRect`)
`snapZoom`	`(options?) => void`	Snap zoom to nearest `zoomSnapLevels`

Types

interface ViewState {
  x: number // horizontal offset in pixels
  y: number // vertical offset in pixels
  zoom: number // scale factor (1 = 100%)
  rotation?: number // angle in degrees (default 0)
}

interface GesturesOptions {
  pan?: boolean // default true
  zoom?: boolean // default true
  rotate?: boolean // default false
}

interface AnimationOptions {
  animate?: boolean // default false
  duration?: number // default 300ms
  easing?: EasingFunction // default easeOut
}

type EasingFunction = (t: number) => number

interface DoubleTapOptions {
  enabled?: boolean // default true
  mode?: "zoomIn" | "reset" | "toggle" // default "toggle"
  step?: number // default 2
}

interface InertiaOptions {
  enabled?: boolean // default true
  friction?: number // 0–1, default 0.92
}

interface BoundsOptions {
  minX?: number
  maxX?: number
  minY?: number
  maxY?: number
  mode?: "clamp" | "bounce" // default "clamp"
}

interface KeyboardOptions {
  enabled?: boolean // default false
  panStep?: number // default 50
  zoomStep?: number // default 1.5
  rotateStep?: number // default 15
}

interface SnapToGridOptions {
  size: number
  mode?: "end" | "always" // default "end"
}

type ZoomSnapLevel = number

interface RotationOptions {
  minAngle?: number
  maxAngle?: number
  snapLevels?: number[] // e.g. [0, 90, 180, 270]
}

interface CursorOptions {
  enabled?: boolean // default true
  idle?: string // default "grab"
  dragging?: string // default "grabbing"
  zooming?: string // default "zoom-in"
}

interface ActivationKeyOptions {
  pan?: string // e.g. "Shift"
  zoom?: string // e.g. "Alt"
  rotate?: string // e.g. "Control"
}

Container Setup

The container element must have touchAction: "none" to prevent the browser from intercepting touch gestures (scroll, pinch-zoom) before the hook can handle them:

<div ref={containerRef} style={{ touchAction: "none", overflow: "hidden" }}>

Without touchAction: "none", pinch-to-zoom and touch drag will trigger native browser behavior instead of your custom handling. The overflow: "hidden" prevents content from leaking outside the viewport.

Browser Compatibility

The hook uses standard Web APIs available in all modern browsers:

Feature	Chrome	Firefox	Safari	Edge	iOS Safari	Android Chrome
Pointer Events	55+	59+	13+	12+	13+	55+
Wheel Events	31+	17+	7+	12+	7+	31+
Touch Events	22+	52+	10+	12+	10+	22+
ResizeObserver	64+	69+	13.1+	79+	13.4+	64+
requestAnimationFrame	10+	23+	6+	12+	6+	10+

Minimum: Chrome/Edge 64+, Firefox 69+, Safari 13.1+, iOS 13.4+.

Safari Gesture Events (GestureEvent) are used when available for native trackpad pinch-zoom on macOS.

Comparison

Feature	useZoomPinch	react-zoom-pan-pinch	@use-gesture/react	motion/react
Size (min+gzip)	~5.2 KB	~13.2 KB	~8.9 KB	~41.6 KB
Approach	Hook	Components + hook	Gesture primitives	Animation + gesture
Controlled mode	✅ Native	❌	❌	❌
DOM wrappers	✅ None	+2 divs	✅ None	+1 div
Bounds / constraints	✅	✅	🔧 Manual	🔧 dragConstraints
Keyboard navigation	✅	❌	❌	❌
Coordinate conversion	✅	❌	❌	❌
Snap to grid	✅	❌	❌	❌
Zoom snap levels	✅	❌	❌	❌
Rotation gestures	✅	❌	🔧 Manual	❌
Ready-to-use zoom/pan	✅	✅	🔧 Manual	🔧 Manual

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github/workflows		.github/workflows
docs		docs
src		src
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

useZoomPinch

Features

Installation

Quick Start

Controlled Mode

Animated Transitions

Built-in Easings

Navigation

Rotation

Gesture Toggles

Double-Tap Zoom

Modes

Inertia

Event Filtering

Granular Events

Bounds

Keyboard Navigation

Coordinate Conversion

Zoom Snap Levels

Snap to Grid

Fit to Content

Pan Button

API

useZoomPinch(options)

Options

Returns

Types

Container Setup

Browser Compatibility

Comparison

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`useZoomPinch(options)`

Packages