Zoom In/Out Images With JavaScript – zoomist.js

Preview:

Description:

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 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. Create a container and set data-zoomist-src attribute with the image URL for Zoomist.

<div id="zoomist" data-zoomist-src="./image.png"></div>

5. Initialize the Zoomist on the container element.

new Zoomist('#zoomist')

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

6. Add custom zoom controls to the image.

<div class="custom-modules">
  <div class="custom-out-zoomer">-</div>
  <div class="custom-slider"></div>
  <div class="custom-in-zoomer">+</div>
</div>

.custom-modules {
  display: flex;
  justify-content: center;
  align-items: center;
  width: 100%;
  margin-top: 50px;
  display: none;
}
.custom-in-zoomer, .custom-out-zoomer {
  width: 30px;
  height: 30px;
  border-radius: 50%;
  box-shadow: 3px 3px 7px rgba(0, 0, 0, .4);
  display: flex;
  justify-content: center;
  align-items: center;
  cursor: pointer;
  margin: 0 10px;
}

7. All available parameters:

new Zoomist('#zoomist',{
    //  'cover' | 'contain' | 'none'
    fill: 'cover',
    // the attribute of image source or a image element
    src: 'data-zoomist-src',
    // {Boolean} set is draggable or not
    draggable: true,
    // {Boolean} set is wheelable or not
    wheelable: true,
    // {Boolean} set is pinchable or not
    pinchable: true,
    // {Boolean} set image can be drag out of the bounds (it will set to false when fill is contain)
    bounds: true,
    // {Number} the ratio of zoom at one time
    zoomRatio: 0.1,
    // {Number > 1, False} the max ratio of the image (compare to the initial image status)
    maxRatio: false,
    // {Boolean / String}
    height: 'auto',
    slider: {
      el: '.custom-slider',
      direction: 'vertical', // 'horizontal' or 'vertical'
      maxRatio: 3
    },
    zoomer: {
      inEl: '.custom-in-zoomer',
      outEl: '.custom-out-zoomer',
      disableOnBounds: true
    },
})

6. API methods.

// Get the { width, height, aspectRatio } of the container
get 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();
// Get the current value of zoom ratio.
zoomist.getZoomRatio();
// 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() Destroy the zoomist and remove all events listeners.

7. Event handlers.

new Zoomist('#zoomist',{
    on: {
      ready() {
        // console.log('ready')
      },
      zoom(ratio) {
        // console.log(this.getZoomRatio(), ratio)
      },
      wheel(event) {
        // console.log(this, event)
      },
      dragStart(transform, event) {
        // console.log('start', transform)
      },
      drag(transform, event) {
        // console.log('drag', transform)
      },
      dragEnd(transform, event) {
        // console.log('end', transform)
      },
      slideStart(value, event) {
        // console.log(value)
      },
      slide(value, event) {
        // console.log(value)
      },
      slideEnd(value, event) {
        // console.log(value)
      },
      pinchStart(event) {
        // do something
      },
      pinch(event) {
        // do something
      },
      pinchEnd(event) {
        // do something
      },
      resize() {
        // console.log('resize')
      },
      reset() {
        // console.log('reset')
      },
      destroy() {
        // console.log('destroy')
      },
      update() {
        // console.log('update')
      }
    }
})

Changelog:

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