Lightweight JavaScript Pinch Zoom Library

Pinch with two fingers on touch, or hold Ctrl and scroll on desktop. Zoom in, then drag to pan. Use Reset to return to 100% zoom or Disable to toggle gestures. For every option on one page, open the hcg-pinch-zoom demo page.

Reset Disable

Scale: 1.00

How hcg-pinch-zoom compares with common alternatives.

Choose hcg-pinch-zoom when you want a tiny vanilla helper for image viewers, maps, and diagrams. Use a heavier library when you need tiled imagery, physics, or a full canvas rendering pipeline.

Everything included in the library at a glance:

• Zero dependencies - one small JavaScript file and a companion CSS file.
• Script tag or bundler - works with a plain script tag, CommonJS, or AMD.
• Touch pinch zoom - two-finger gesture on phones and tablets.
• Safari trackpad pinch - via gesturestart / gesturechange.
• Trackpad pinch and Ctrl + wheel - real ctrlKey detection on wheel.
• Built-in drag while zoomed - pan when scale !== initialScale.
• Focal-point zoom - zoom toward cursor or pinch midpoint.
• Scale limits - minScale, maxScale, and initialScale.
• Slider sync - drive zoom from HTML range inputs with setScale().
• Data-attribute init - data-hcg-pinch-zoom and data-hcg-* options.
• Callbacks - onZoom and onPan for UI sync.
• Static helpers - get(), destroy(), reset(), destroyAll().
• Multiple instances - independent viewports on the same page.
• React-friendly - create in useEffect and call destroy() on unmount.

Direct download

Source code and package:

GitHub npm JavaScript (hcg-pinch-zoom.js) CSS (hcg-pinch-zoom.css)

Download hcg-pinch-zoom.js and hcg-pinch-zoom.css, then include both on your page:

HTML

<link rel="stylesheet" href="hcg-pinch-zoom.css">
<script src="hcg-pinch-zoom.js"></script>

npm

Install from npm:

Command Line

npm install hcg-pinch-zoom

CommonJS (require):

JavaScript

const hcgPinchZoom = require("hcg-pinch-zoom");
// also load hcg-pinch-zoom.css however your bundler handles CSS

ESM (import):

JavaScript

import hcgPinchZoom from "hcg-pinch-zoom";
import "hcg-pinch-zoom/hcg-pinch-zoom.css";

CDN usage

Load from a CDN with one script and one stylesheet - no npm or bundler required. The global hcgPinchZoom function is available as soon as the script finishes loading.

jsDelivr:

HTML

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/hcg-pinch-zoom@1/hcg-pinch-zoom.css">
<script src="https://cdn.jsdelivr.net/npm/hcg-pinch-zoom@1/hcg-pinch-zoom.js"></script>

unpkg:

HTML

<link rel="stylesheet" href="https://unpkg.com/hcg-pinch-zoom@1/hcg-pinch-zoom.css">
<script src="https://unpkg.com/hcg-pinch-zoom@1/hcg-pinch-zoom.js"></script>

Install hcg-pinch-zoom, wrap zoomable content in a viewport with overflow: hidden, then init with a data attribute or JavaScript.

Initialize the viewport

Include CSS and JS, add a viewport element, and call hcgPinchZoom() or use data-hcg-pinch-zoom for auto-init.

HTML

<link rel="stylesheet" href="hcg-pinch-zoom.css">

<div class="viewport">
  <img src="photo.jpg" alt="Photo">
</div>

<script src="hcg-pinch-zoom.js"></script>
<script>
  const pz = hcgPinchZoom('.viewport', {
    minScale: 0.5,
    maxScale: 4,
    drag: true,
    onZoom(detail) {
      console.log('scale', detail.scale);
    }
  });
</script>

Data-attribute auto-init

Add data-hcg-pinch-zoom to the viewport. Options map to data-hcg-* attributes (see data-hcg attribute mapping).

HTML

<div data-hcg-pinch-zoom data-hcg-min-scale="0.5" data-hcg-max-scale="4">
  <img src="photo.jpg" alt="Photo">
</div>

Instance methods

Store the returned instance and call its methods whenever you need them.

JavaScript

const scale = pz.getScale();
pz.setScale(2);
pz.reset();
pz.disable();
pz.enable();
pz.destroy();
console.log(hcgPinchZoom.version);

Sync an HTML range slider with pinch zoom using setScale(). Use onZoom to update the slider when the user pinches or scrolls. Try it on the Slider zoom demo.

Range input sync

JavaScript

const viewport = document.querySelector('.viewport');
const slider = document.querySelector('#zoom-slider');

const pz = hcgPinchZoom(viewport, {
  minScale: 0.5,
  maxScale: 4,
  onZoom(detail) {
    slider.value = detail.scale;
  }
});

slider.addEventListener('input', () => {
  const scaleValue = Number(slider.value);
  const rect = viewport.getBoundingClientRect();
  pz.setScale(scaleValue, {
    clientX: rect.left + rect.width / 2,
    clientY: rect.top + rect.height / 2
  });
});

Reset without storing the instance

Use the static hcgPinchZoom.reset(selector) helper from toolbar buttons. See reset() method reference for the instance API.

Import hcgPinchZoom from the package and create the viewport inside useEffect. Call destroy() in the cleanup function when the component unmounts.

Try the live React demo on StackBlitz

Zoom viewport component

JavaScript

import { useEffect, useRef } from "react";
import hcgPinchZoom from "hcg-pinch-zoom";
import "hcg-pinch-zoom/hcg-pinch-zoom.css";

function ZoomViewport({ src, alt }) {
  const ref = useRef(null);

  useEffect(() => {
    const instance = hcgPinchZoom(ref.current, {
      minScale: 0.5,
      maxScale: 4,
      onZoom(detail) {
        console.log(detail.scale);
      }
    });
    return () => instance.destroy();
  }, []);

  return (
    <div ref={ref} className="zoom-viewport">
      <img src={src} alt={alt} />
    </div>
  );
}

export default ZoomViewport;

Load hcg-pinch-zoom.css once in your app entry or import it in the component. Use disable() and enable() from props or effects when you need to lock zoom during async work.

Create as many zoom viewports on a page as you need. Each call to hcgPinchZoom() returns a fully independent instance with its own scale, position, options, and API.

<link rel="stylesheet" href="hcg-pinch-zoom.css">

<div id="photo-a" class="viewport"><img src="a.jpg" alt="Photo A"></div>
<div id="photo-b" class="viewport"><img src="b.jpg" alt="Photo B"></div>

<script src="hcg-pinch-zoom.js"></script>
<script>
  const zoomA = hcgPinchZoom(document.getElementById('photo-a'), { maxScale: 6 });
  const zoomB = hcgPinchZoom(document.getElementById('photo-b'), { maxScale: 3 });

  zoomA.reset();
  zoomB.getScale();
</script>

• Link hcg-pinch-zoom.css once and initialize as many viewports as you need.
• Static helpers accept a selector: hcgPinchZoom.reset('#photo-a').
• Call each instance's destroy() when removing it from the DOM.

All default styles live in hcg-pinch-zoom.css, using plain single-class selectors. Edit that file directly, or override any rule from your own stylesheet loaded after it.

• .hcg-pinch-zoom - the viewport (clips overflow, sets touch-action: none)
• .hcg-pinch-zoom-content - the zoomable transform target
• .hcg-pinch-zoom-draggable / .hcg-pinch-zoom-dragging - grab cursors while zoomed and during drag
• .hcg-pinch-zoom-disabled - reduced opacity and no pointer events when disabled

.hcg-pinch-zoom { height: 320px; border: 1px solid #e5e7eb; border-radius: 10px; background: #f9fafb; }
.hcg-pinch-zoom-content img { display: block; width: 100%; height: auto; pointer-events: none; }
.hcg-pinch-zoom-disabled { opacity: 0.5; }

Copy-paste examples for each option. See the options types and defaults table for reference values.

content

CSS selector string or element to transform. Default: first child of the viewport, or the viewport itself if empty.

JavaScript

hcgPinchZoom('#viewport', {
  content: 'img'
});

hcgPinchZoom('#viewport', {
  content: document.querySelector('.zoom-target')
});

minScale

Minimum zoom level. Default: 0.5 (50%).

JavaScript

hcgPinchZoom('#viewport', {
  minScale: 0.5
});

HTML

<div data-hcg-pinch-zoom data-hcg-min-scale="0.5">
  <img src="photo.jpg" alt="Photo">
</div>

maxScale

Maximum zoom level. Default: 4 (400%).

JavaScript

hcgPinchZoom('#viewport', {
  maxScale: 8
});

initialScale

Starting zoom level and the scale at which drag is disabled. Default: 1 (100%). Position resets when scale equals initialScale.

JavaScript

hcgPinchZoom('#viewport', {
  initialScale: 1
});

wheel

Enable touchpad pinch and Ctrl+mouse-wheel zoom. Default: true. Plain scroll (no Ctrl) passes through.

JavaScript

hcgPinchZoom('#viewport', {
  wheel: true
});

pz.setOption('wheel', false);

pinch

Enable two-finger touch pinch and Safari gesture events. Default: true.

JavaScript

hcgPinchZoom('#viewport', {
  pinch: true
});

pz.setOption('pinch', false);

drag

Enable built-in drag while zoomed. Active only when scale !== initialScale. Default: true.

JavaScript

hcgPinchZoom('#viewport', {
  drag: true
});

hcgPinchZoom('#viewport', {
  drag: false   // zoom only, no pan
});

trackpadSensitivity

Exponential wheel zoom speed for trackpad pinch (ctrlKey without real Ctrl held). Default: 0.01.

JavaScript

hcgPinchZoom('#viewport', {
  trackpadSensitivity: 0.015
});

ctrlWheelSensitivity

Exponential wheel zoom speed when the user holds Ctrl and scrolls the mouse wheel. Default: 0.003.

JavaScript

hcgPinchZoom('#viewport', {
  ctrlWheelSensitivity: 0.005
});

maxWheelStep

Clamp each wheel deltaY (after normalization) to limit zoom speed per event. Default: 40.

JavaScript

hcgPinchZoom('#viewport', {
  maxWheelStep: 30
});

disabled

Start with zoom and drag disabled. Call enable() to activate. Default: false.

JavaScript

const pz = hcgPinchZoom('#viewport', { disabled: true });
pz.enable();

onZoom event

Called when scale changes (pinch, wheel, or setScale()). Not fired on initial setup. Receives { scale, x, y, target }.

onZoom event example

onPan event

Called while dragging the zoomed content. Receives { scale, x, y, target }.

onPan event example

Pass these as the second argument to hcgPinchZoom(element, options). Options can be changed at runtime with setOption(name, value).

hcgPinchZoom(element, options) returns an instance with these methods. The factory also exposes hcgPinchZoom.version, get(), destroy(), reset(), init(), and destroyAll().

getScale()

Return the current scale value.

JavaScript

const scale = pz.getScale();

setScale(scale, focal?)

Apply zoom and update the DOM. Optional focal point: { clientX, clientY } in screen coordinates. Without focal, zooms toward the viewport center.

JavaScript

pz.setScale(2);

pz.setScale(1.5, {
  clientX: 400,
  clientY: 300
});

getTransform() / setTransform({ x, y, scale })

Read or set translate and scale together.

JavaScript

const { x, y, scale } = pz.getTransform();

pz.setTransform({ x: 0, y: 0, scale: 1 });

reset()

Reset to initialScale and origin position (0, 0).

JavaScript

pz.reset();

// Without storing the instance:
hcgPinchZoom.reset('#viewport');

enable() / disable()

Turn gestures on or off at runtime.

JavaScript

pz.disable();
pz.enable();

setOption(name, value)

Update any option at runtime. Changing minScale, maxScale, or initialScale re-clamps the current scale.

JavaScript

pz.setOption('maxScale', 6);
pz.setOption('drag', false);
pz.setOption('onZoom', (detail) => console.log(detail.scale));

destroy()

Remove listeners, classes, and the instance reference from the element.

JavaScript

pz.destroy();

hcgPinchZoom.destroy('#viewport');   // static helper

Static: get(), init(), destroyAll(), version

hcgPinchZoom.get(target) returns the instance or null. init(root?) scans for data-hcg-pinch-zoom. destroyAll() destroys every instance.

JavaScript

const pz = hcgPinchZoom.get('#viewport');

hcgPinchZoom.init();
hcgPinchZoom.destroyAll();

console.log(hcgPinchZoom.version);

Every option that takes a simple value can be set in HTML. Mark the viewport with data-hcg-pinch-zoom; elements are initialized automatically on page load. Boolean and numeric options use data-hcg-* attributes as shown below.

<div
  data-hcg-pinch-zoom
  data-hcg-min-scale="0.5"
  data-hcg-max-scale="4"
  data-hcg-drag="true">
  <img src="photo.jpg" alt="Photo">
</div>

The library reports zoom and pan changes through onZoom and onPan options rather than custom DOM events. Pass them when you create the instance, or update them later with setOption().

onZoom

Fires when scale changes (pinch, wheel, or setScale()). Not fired on initial setup. Detail: { scale, x, y, target }. Use to sync HTML sliders, toolbar buttons, or a scale readout. For bidirectional slider sync, see the slider sync section.

JavaScript

const readout = document.querySelector('#zoom-readout');

const pz = hcgPinchZoom('#viewport', {
  onZoom(detail) {
    readout.textContent = Math.round(detail.scale * 100) + '%';
  }
});

onPan

Fires while dragging zoomed content. Detail: { scale, x, y, target }. x and y are translate values in pixels.

JavaScript

hcgPinchZoom('#viewport', {
  onPan(detail) {
    console.log('pan', detail.x, detail.y, 'scale', detail.scale);
  }
});

Change callbacks at runtime

Replace a callback after init with setOption().

JavaScript

pz.setOption('onZoom', (detail) => {
  console.log('New handler', detail.scale);
});

pz.setOption('onPan', (detail) => {
  console.log('Pan at', detail.x, detail.y);
});

hcg-pinch-zoom works in modern browsers that support touch events, pointer events, wheel listeners, and Safari gesture events where available.

Released under the MIT License. Free for personal and commercial use. Copyright HTML Code Generator.