@magic-spells/image-zoom

Pinch-to-zoom and pan web component for images. Mobile-first, light-DOM, no dependencies.

🔍 Live Demo - See it in action!

Install

npm install @magic-spells/image-zoom

Usage

import '@magic-spells/image-zoom';
import '@magic-spells/image-zoom/css';

<image-zoom min="1" max="3">
  <img src="photo.jpg" alt="" />
</image-zoom>

• Mobile: two-finger pinch to zoom, one-finger drag to pan when zoomed.
• Desktop: double-click to toggle between min and max.
• Rubber-band resistance when pinching below min or above max, with animated snap-back on release.

Attributes

| Attribute | Default | Description | |---|---|---| | min | 1 | Minimum scale multiplier. 1 = image fills the container (contain-fit). | | max | 3 | Maximum scale multiplier. |

Events

| Event | Detail | Description | |---|---|---| | image-zoom:zoomstart | { scale } | A pinch gesture begins, or a programmatic reset() / zoomTo() / double-tap is about to change the transform. Suppressed when the call is a no-op. | | image-zoom:zoomend | { scale } | A pinch gesture has settled, or a programmatic transform change has been committed. Fires immediately after the commit, not after the CSS transition completes. | | image-zoom:change | { scale, translateX, translateY } | Any transform update (fires frequently during gestures). |

Public API

const el = document.querySelector('image-zoom');
el.scale;           // current scale (number)
el.min;             // minimum scale
el.max;             // maximum scale
el.reset();         // animate back to min, recentered
el.zoomTo(2);       // animate to a specific scale
el.zoomTo(2, { animate: false });

CSS variables

| Variable | Default | Description | |---|---|---| | --image-zoom-bg | #000 | Background color of the container | | --image-zoom-radius | 0 | Border radius | | --image-zoom-aspect | 4 / 3 | aspect-ratio of the container | | --image-zoom-cursor | grab | Cursor when idle | | --image-zoom-cursor-active | grabbing | Cursor when gesturing / zoomed | | --image-zoom-transition-duration | 300ms | Snap-back animation duration | | --image-zoom-transition-easing | cubic-bezier(0.22, 1, 0.36, 1) | Snap-back easing |

License

MIT