react-zoom-pan-pinch

react-zoom-pan-pinch adds mouse-wheel zoom, click-and-drag panning, and touch pinch-to-zoom to any HTML element — images, divs, SVGs, or entire component trees — via a TransformWrapper/TransformComponent pair and a useTransformContext/useControls hook API. It handles the interaction math (bounds clamping, velocity-based momentum, double-tap/double-click zoom, animated transitions) that would otherwise take significant custom work to get feeling right across mouse and touch input.

It’s commonly reached for when building image viewers, diagram/canvas tools (in the vein of Figma or Miro-style pan-and-zoom canvases), and PDF or map-like viewers inside a React app, without pulling in a full canvas/graphics engine.

What You Get

• TransformWrapper/TransformComponent components that add zoom/pan/pinch to any wrapped children with minimal setup
• Mouse wheel zoom, click-and-drag panning, and touch pinch-to-zoom gestures out of the box
• Programmatic control hooks (useControls, useTransformEffect) for zoom-to-point, reset, and custom UI controls
• Bounds clamping and velocity-based momentum/animation so panning and zooming feel physically natural
• A MiniMap component for rendering a navigable overview of the zoomed/panned content

Common Use Cases

• Building an image viewer or gallery with pinch-to-zoom and pan on both desktop and mobile
• Implementing a Figma/Miro-style infinite canvas or diagram editor that needs zoom and pan without a full canvas engine
• Adding zoomable, pannable PDF page or map-style viewers to a React application
• Giving product screenshots or technical diagrams an interactive zoom-and-pan experience in documentation sites

Under The Hood

Architecture The library is organized around a TransformWrapper context provider (src/components/transform-wrapper) that owns interaction state (scale, position, velocity) and a TransformComponent (src/components/transform-component) that applies the computed CSS transform to its children; src/core contains the gesture and calculation logic (wheel, pinch, pan handlers and bounds/velocity math in src/models/calculations.model), decoupled from the React-specific hooks in src/hooks (use-controls, use-transform-context, use-zoom-pan-pinch) that expose that core logic to consumer components, plus optional add-ons like keep-scale, mini-map, and virtualize for specialized rendering needs.

Tech Stack TypeScript, built with Rollup producing both CJS and ESM bundles, developed against a Storybook-driven component workshop (.storybook/) for visual development and documentation, tested with Jest, and released via semantic-release; React and react-dom are peer dependencies only, keeping the library framework-version-agnostic within React’s ecosystem.

Code Quality The __tests__ directory is organized by concern (features/, utils/, examples/, regressions/), with a dedicated regressions/ folder indicating the maintainer tracks and guards against previously reported bugs — a good practice signal; the docs/ directory further separates feature-requests/, bugs/, and invalid-issues/, suggesting an organized issue-triage workflow alongside the code itself.

API Design The core API — wrap content in TransformWrapper > TransformComponent — is minimal for the default case, while useControls and useTransformEffect expose an escape hatch for building custom zoom/reset buttons or reacting to transform state changes; this two-tier design (zero-config default, hooks for customization) keeps the common path simple while still supporting the diagram-editor-style use cases that need fine-grained programmatic control.