Zoom Image On Hover & Wheel & Pinch – Zoom Image

A mobile-compatible framework-agnostic image zoom component that supports click, mouse wheel scrolling, hover actions, and pinch-to-zoom gestures.

Perfect for e-commerce web developers who want to provide an interactive image viewing experience.

How to use it:

1. Install and import the Zoom Image component.

# Yarn
$ yarn add @zoom-image/core
# NPM
$ npm i @zoom-image/core

import { createZoomImageClick, createZoomImageHover, createZoomImageMove, createZoomImageWheel, cropImage } from "@zoom-image/core"

2. Add an image to the page.

<div id="example" class="image-viewer">
  <img src="image.webp" />
</div>

.image-viewer {
  width: 400px;
  height: 400px;
  cursor: crosshair;
}
img {
  width: 100%;
  height: 100%;
}

3. Call the function on the top container. That’s it.

const container = document.getElementById("example")
// zoom on click
createZoomImageClick(container);
// zoom on hover
createZoomImageHover(container);
// zoom on move
createZoomImageMove(container);
// zoom on wheel
createZoomImageWheel(container);
// crop image
const croppedImage = await cropImage()

4. Available options.

// zoom on click
createZoomImageClick(container,{
  // Props for the zoomed image
  zoomImageProps?: {
    alt?: string
  }
  // Zoom scale, default is 4
  zoomFactor?: number
  // The source of zoomed image, default is the same as the original image
  zoomImageSource?: string
  // Zoom on move
  disableScrollLock?: boolean
});

// zoom on hover
createZoomImageHover(container,{
  // The size of zoomed window where zoomed image will be displayed
  customZoom: { width: number; height: number }
  // Props for the zoomed image
  zoomImageProps?: {
    alt?: string
  }
  // The source of zoomed image, default is the same as the original image
  zoomImageSource?: string
  // The css classes will be added to zoom lens element
  zoomLensClass?: string
  // The smaller the value, the bigger zoomed image and smaller zoom lens, default is 1
  zoomLensScale?: <PartialCSSStyleDeclaration>
  // The container of zoomed image
  zoomTarget: HTMLElement
  // The css classes will be added to zoomed image container on zoom
  zoomTargetClass?: string
  // The scale of zoomed image, default is 2
  scale?: number
  // Disable scroll lock on zoom, default is false
  disableScrollLock?: boolean
});

// zoom on move
createZoomImageMove(container,{
  // Props for the zoomed image
  zoomImageProps?: {
    alt?: string,
    className?: string,
  }
  // Zoom scale, default is 4
  zoomFactor?: number
  // The source of zoomed image, default is the same as the original image
  zoomImageSource?: string
  // Disable context menu
  disabledContextMenu?: boolean
});

// zoom on wheel
createZoomImageWheel(container,{
  // Maximum zoom scale, default is 4
  maxZoom?: number
  // Zoom ratio when scrolling, default is 0.1
  wheelZoomRatio?: number
  // Animation duration for zooming on double tap, default is 300 ms
  dblTapAnimationDuration?: number
  // Partial or full initial state
  // useful for storing previous zoomed state and re-initialize it on load
  initialState?: <PartialZoomImageWheelState>
  // Predicate function to determine if zoom should be triggered on a single touch action
  shouldZoomOnSingleTouch?: () => boolean
  // Zoom target element, default is the closest image element inside a container
  zoomTarget?: HTMLElement | null
});

// Crop image
const croppedImage = await cropImage({
  // Zoom image element
  image: HTMLImageElement
  // Current zoom positionX returned from createZoomImageWheel
  positionX: number
  // Current zoom positionY returned from createZoomImageWheel
  positionY: number
  // Current zoom level from createZoomImageWheel
  currentZoom: number
  // Current rotation from createZoomImageWheel - default 0
  rotation?: number
})

Changelog:

v0.42.0 (01/28/2026)

• Support custom zoom target container with dynamic element updates via state

v0.41.4 (11/27/2025)

• Fix zoom on move for Firefox

v0.41.0 (06/08/2025)

• add support for zooming with multiple fingers

v0.40.0 (03/01/2025)

• Improve zoom wheel performance

v0.39.0 (10/06/2024)

• feat: add className option to zoom image move

v0.38.0 (09/04/2024)

• Add support for preventing zoom on single touch

v0.37.1 (09/04/2024)

• Fix zoom move not working on multi-fingers usage

v0.37.0 (08/30/2024)

• Optimize rendering for zoom on move

v0.36.2 (06/09/2024)

• Fix scroll lock on mobile – all zoom

v0.36.1 (06/07/2024)

• Fix zoom image move – zoomed image distorted on mobile phone

v0.36.0 (06/07/2024)

• Add support for disabledContextMenu option on zoom image move

v0.35.1 (06/06/2024)

• Fix zoom image move on mobile

v0.35.0 (06/02/2024)

• feat: add support for initial state of zoom wheel

v0.34.3 (05/11/2024)

• Prevent jump when zooming out with double tap

v0.34.2 (05/09/2024)

• Make pinch zooming behaviour more intuitive
• Fix zoom on wheel when going from two to one touch

v0.33.3 (04/04/2024)

• patch: support multiple module styles

v0.33.2 (03/26/2024)

• fix: zoomed image click cause extra border display on first render

v0.33.1 (03/20/2024)

• Fix cropImage util on rotation larger than 360

v0.33.0 (02/18/2024)

• Add zoomImageProps to zoom click, hover and move

v0.32.2/1 (02/18/2024)

• Fix zoom on wheel with rotation

v0.32.0/1 (12/03/2023)

• Fix zoom on hover across browsers
• Improve zoom on hover – handle dynamic dimensions

v0.31.0 (12/03/2023)

• Fix zoom on wheel rotation over 360 degrees

v0.30.1 (11/14/2023)

• Improve zoom move performance

v0.30.0 (11/14/2023)

• Add rotation feature to zoom image wheel.

v0.29.1 (11/13/2023)

• Fix zoom image move – disableScrollLock option

v0.29.0 (11/13/2023)

• Improve zoom image on hover performance

v0.28.0 (10/11/2023)

• Add disableScrollLock option to zoom on hover and zoom on

v0.27.0 (10/10/2023)

• Optimize

v0.26.1 (10/09/2023)

• Fix image loading issue during development mode

v0.26.0 (10/09/2023)

• Add disableScrollLock option to zoom on move

v0.25.0 (10/06/2023)

• Improve bundle size by removing unnecessary caching layer

v0.24.0 (09/30/2023)

• Bugfix

v0.21.1 (09/28/2023)

• Bugfix

v0.21.0 (08/06/2023)

• Bugfix

v0.20.0 (07/15/2023)

• Fix state initialization and update internal dependencies

v0.19.0 (07/01/2023)

• Update dependencies

v0.18.1 (06/16/2023)

• Bugfix

v0.18.0 (06/14/2023)

• Enhance zoom wheel

v0.17.0 (06/03/2023)

• Update

v0.16.1 (05/29/2023)

• Clean up remove event listener usage

v0.14.0 (05/21/2023)

• Clean up remove event listener usage

v0.13.0 (05/21/2023)

• Add immutability and cut down bundle size

v0.12.0 (05/18/2023)

• Expose more internal types to client code

v0.11.0 (05/17/2023)

• bugfix

v0.11.0 (05/17/2023)

• Refactor internal store

v0.10.0 (05/16/2023)

• optimize normal store setState

v0.9.0 (05/16/2023)

• fix zoom wheel on update

v0.8.0 (05/16/2023)

• Expose currentZoom property in wheel zoom

v0.7.0 (05/16/2023)

• Add crop image utility

v0.6.0 (05/14/2023)

• Refactor image cache usage

v0.5.0 (05/13/2023)

• Add support for zooming image on click

v0.4.0 (05/12/2023)

• Add image caching mechanism

v0.3.0 (05/12/2023)

• Add zoomed image status
• Migrate background-size to image
• Create simple store for state management

v0.2.1 (05/11/2023)

• Add support for zooming image on move