Zoom In/Out Images With JavaScript – zoomist.js

zoomist.js is a tiny JavaScript library for zoom and panning images using the mouse wheel & drag. Also supports custom zoom controls like sliders and buttons.

The library allows users to interact with the content of the image by changing its magnification level. It does not require any external dependencies such as jQuery or other libraries that might conflict with your application codebase.

How to use it:

1. Install & download the package.

# NPM
$ npm i zoomist

2. If you download the files via npm, you just need to import Zoomist in your own project :

// import Zoomist styles
import 'zoomist/css'
// import Zoomist
import Zoomist from 'zoomist'

3. If you include the zoomist library with tag, you need to add CSS as well.

<link rel="stylesheet" src="zoomist.min.css"/>
<script src="zoomist.min.js"></script>

4. Add your image to the zoomist container.

<!-- zoomist-container -->
<div class="zoomist-container">
  <!-- zoomist-wrapper is required -->
  <div class="zoomist-wrapper">
    <!-- zoomist-image is required -->
    <div class="zoomist-image">
      <!-- you can add anything you want to zoom here. -->
      <img src="..." />
    </div>
  </div>
</div>

5. Initialize the Zoomist on the container element.

new Zoomist('#zoomist')

// OR
const zoomistElement = document.querySelector('#zoomist')

6. Add custom styles.

.zoomist-container {
  width: 100%;
  max-width: 600px;
}
.zoomist-image {
  width: 100%;
  aspect-ratio: 1;
}
.zoomist-image img {
  width: 100%;
  height: 100%;
  object-fit: cover;
  object-position: center;
}

7. All available parameters:

new Zoomist('#zoomist',{
    // set is draggable or not
    draggable: true,
    // set is wheelable or not
    wheelable: true,
    // set is pinchable or not
    pinchable: true,
    // set image stuck on bounds
    bounds: true,
    // the ratio of zooming at one time
    zoomRatio: 0.1,
    // the max scale of zoomist-image (must be number larger then initScale)
    maxScale: 10,
    // the min scale of zoomist-image (must be number smaller then initScale)
    minScale: 1,
    // set initial scale of zoomist-image
    initScale: null,
    // if set to true, enable to release touch events to allow for further page scrolling when .zoomist-image is on bounds.
    dragReleaseOnBounds: false,
    // if set to true, enable to release wheel events to allow for further page scrolling when .zoomist-image is on mixScale or maxScale.
    wheelReleaseOnMinMax: false,
    // elements matched this class will not be dragged.
    disableDraggingClass: '${p}-not-draggable',
    // elements matched this class will not be zoomed by mouse wheel.
    disableWheelingClass: '${p}-not-wheelable',
    // if set to true, enable to smooth drag
    smooth: false,
    // zoomist slider module
    slider: {
      // the css selector string or a element of the slider
      el: null,
      // the direction of the slider 'horizontal' or 'vertical'
      direction: 'horizontal'
    },
    //
    zoomer: {
      // the wrapper of all zoomer buttons
      el: null,
      // the css selector string or a element for in-zoomer
      inEl: null,
      // the css selector string or a element for out-zoomer
      outEl: null,
      // the css selector string or a element for reset-zoomer
      resetEl: null,
      // in zoomer and out zoomer will be disabled when image comes to maximin or minimum
      disabledClass: 'zoomist-zoomer-disabled'
    }
})

8. API methods.

// Get the { width, height, aspectRatio } of the container
zoomist.getContainerData();
// Get the { width, height, aspectRatio, top, left, naturalWidth, naturalHeight } of the image.
zoomist.getImageData();
// Get the current value of the slider.
zoomist.getSliderValue();
// Zoom the image
zoomist.zoom(ratio);
// Zoom the image with a absolute ratio.
// ratio > 0
zoomist.zoomTo(ratio);
// Slide to a specific value
zoomist.slideTo(value, isOnlySlide);
// Move the image
zoomist.move(x, y)
zoomist.moveTo(x, y)
// Reset
zoomist.reset();
// Update
zoomist.update();
// Destroy
zoomist.destroy(cleanStyle)
zoomist.destroySlider()
zoomist.destroyZoomer()
zoomist.destroyModules()

9. Event handlers.

new Zoomist('#zoomist',{
    on: {
      // invoked when zoomist instance ready
      ready(zoomist) {...},
      // invoked when reset methods be used
      reset(zoomist) {...},
      // invoked when image changes it's size
      resize(zoomist) {...},
      // invoked before destroy methods be used
      beforeDestroy(zoomist) {...},
      // invoked after destroy methods be used
      destroy(zoomist) {...},
      // invoked before update methods be used
      beforeUpdate(zoomist) {...},
      // invoked when update methods be used
      update(zoomist) {...},
      // invoked when image is zooming
      zoom(zoomist, scale) {...},
      // invoked when wheeling
      wheel(zoomist, scale, event) {...},
      // invoked when mousedown on wrapper
      dragStart(zoomist, transform, event) {...},
      // invoked when dragging the image
      drag(zoomist, transform, event) {...},
      // invoked when mouseup on wrapper
      dragEnd(zoomist, transform, event) {...},
      // invoked when mousedown on wrapper
      pinchStart(zoomist, scale, event) {...},
      // invoked when pinching the image
      pinch(zoomist, scale, event) {...},
      // invoked when mouseup on wrapper
      pinchEnd(zoomist, scale, event) {...},
      // invoked when mousedown on slider
      slideStart(zoomist, value, event) {...},
      // invoked when sliding the slider
      slide(zoomist, value, event) {...},
      // invoked when mouseup on slider
      slideEnd(zoomist, value, event) {...}
    }
})

Changelog:

v2.2.0 (03/16/2025)

• Add smooth option for smoother dragging experience.

v2.1.1 (06/15/2024)

• Fixed typo

v2.1.0 (06/14/2024)

• NEW feature: dragReleaseOnBounds, wheelReleaseOnMinMax, disableDraggingClass, disableWheelingClass

v2.0.12 (06/05/2024)

• add type button to zoomers

v2.0.10 (10/05/2023)

• v2 released

v1.1.1 (03/29/2022)

• Fixed security problem.

v1.1.0 (03/27/2022)

• Added move and moveTo methods.

v1.0.1 (12/29/2021)

• support mobile devices
• fix pinch bug