hcg-pinch-zoom - JavaScript Pinch Zoom Library

A lightweight, zero-dependency JavaScript pinch zoom library for image viewers, maps, diagrams, and canvas content. Zoom with touch pinch, Safari trackpad gestures, trackpad pinch (wheel + ctrlKey), or Ctrl + mouse wheel. Built-in drag pans the content while zoomed.

• npm: npmjs.com/package/hcg-pinch-zoom
• Documentation & demo: html-code-generator.com/javascript/pinch-zoom-library

hcg-pinch-zoom features

• Zero dependencies - one small JS file and companion CSS
• Touch pinch, trackpad pinch, and Ctrl + wheel zoom
• Built-in drag while zoomed (scale !== initialScale)
• minScale, maxScale, and initialScale with focal-point zoom math
• setScale(), reset(), getTransform(), and setTransform()
• data-hcg-pinch-zoom auto-init and data-hcg-* options
• Clickable buttons and links inside zoomable content
• React-friendly - create in useEffect, call destroy() on unmount

Demo

See the live documentation and interactive demo on the website:

https://www.html-code-generator.com/javascript/pinch-zoom-library

Open index.html in this repository for a local demo page.

React on StackBlitz: stackblitz.com/edit/hcg-pinch-zoom-react

Install hcg-pinch-zoom

Download

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

CDN

jsDelivr (npm):

<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:

<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>

Load CSS before JS. The global hcgPinchZoom function is available immediately after the script loads.

npm

npm install hcg-pinch-zoom

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

hcg-pinch-zoom usage

Basic viewport

<div class="viewport" data-hcg-pinch-zoom>
  <img src="photo.jpg" alt="Photo">
</div>

hcgPinchZoom("#viewport", {
  minScale: 0.5,
  maxScale: 4,
  wheel: true,
  pinch: true,
  drag: true
});

Zoom inputs

Input	How it works
Touch pinch	Two-finger gesture on touch devices
Touchpad pinch	wheel event with ctrlKey
Ctrl + mouse wheel	Same wheel handler with ctrlKey

Data attributes

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

Attribute	Maps to
data-hcg-pinch-zoom	enables auto-init
data-hcg-content	content
data-hcg-min-scale	minScale
data-hcg-max-scale	maxScale
data-hcg-initial-scale	initialScale
data-hcg-wheel	wheel
data-hcg-pinch	pinch
data-hcg-drag	drag
data-hcg-disabled	disabled

Instance API

const pz = hcgPinchZoom("#viewport");

pz.setScale(2);
pz.reset();
pz.getScale();
pz.getTransform();
pz.setTransform({ scale: 1.5, x: 0, y: 0 });
pz.disable();
pz.enable();
pz.destroy();

hcgPinchZoom.reset("#viewport");
hcgPinchZoom.get("#viewport");

Method	Description
hcgPinchZoom(target, options?)	Create one or more instances
setScale(scale, focal?)	Set scale; optional { clientX, clientY } focal point
reset()	Return to initialScale and origin
getTransform()	{ x, y, scale }
setTransform({ x, y, scale })	Apply transform values
disable() / enable()	Toggle gestures
destroy()	Remove listeners and reset styles
hcgPinchZoom.init(root?)	Scan for data-hcg-pinch-zoom
hcgPinchZoom.version	Library version string

License

MIT - see LICENSE.