HOVER THIS ☝

❗❗❗ Next version of Zoomist is out! Let's checkout zoomist v2 ❗❗❗

Zoomist.js is a JavaScript library for zooming image.
And also support mobile device.

Demo Getting Started

Getting Started

Download

Via npm

npm install zoomist@1

Manual download

Download ZIP

Installation

ES modules

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

import Zoomist from 'zoomist'

Script tag include

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

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

<script src="zoomist.min.js"></script>

or using CDN

<link rel="stylesheet" src="https://cdn.jsdelivr.net/npm/zoomist@1/dist/zoomist.min.css"/>
            
<script src="https://cdn.jsdelivr.net/npm/zoomist@1/dist/zoomist.min.js"></script>

Basic Usage

HTML

Create an container and set data-zoomist-src attribute with image URL for Zoomist.

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

JavaScript

Initialize Zoomist in JavaScript.

// syntax
new Zoomist(element[, options])

// for example
new Zoomist('#my-zoomist')

// advanced usage
const myZoomist = document.querySelector('#my-zoomist')
new Zoomist(zoomistElement, {
  // optional parameters
  maxRatio: 4,
  height: '60%',
  // if you need silder
  slider: true,
  // if you need zoomer
  zoomer: true,
  // event
  on: {
    ready() {
      console.log('Zoomist ready!')
    }
  }
})

See some Documentation

Parameters

All available parameters :

Name Type Default Description
src string | IMG element 'data-zoomist-src' Set the url attribute of image. (Or you can set value as a HTML IMG element.)
fill 'cover' | 'contain' | 'none' 'cover' Set the image fill type.
draggable boolean true Set image is draggable or not.
wheelable boolean true Set image is zoomable when mouse wheeling.
pinchable boolean true Set image is pinchable when pinching. (Only works on mobile device)
bounds boolean true Set image can be drag out of bounds or not.

If set fill to 'contain', the value of bounds will be set to false.
zoomRatio number 0.1 Set the ratio of a zoom.
maxRatio number | false false Set the max ratio of the image.

The value of maxRatio can't less than 1.
height 'auto' | '...%' | number | false 'auto' Set the height of the container.
If value is a Number - will set a static height px.
If value is a percentage string - will set a percentage height.
If value is 'auto' - will set a percentage height just like image.
If value is false - won't set height to the container.
slider boolean | sliderOptions Object with slider parameters or boolean true to enable with default settings. 
new Zoomist('#my-zoomist', {
  slider: {
    el: '.custom-slider',
    direction: 'vertical'
  }
})
{
el string | querySelector null String with CSS selector or querySelector of slider. If el set to false zoomist will create a silder for you.
direction 'horizontal' | 'vertical' 'horizontal' Set the direction of slider.
maxRatio number 2 Set the max ratio of image when slider value is 100.

Only works on options.maxRatio is false
}
zoomer boolean | zoomerOptions Object with zoomer parameters or boolean true to enable with default settings. 
new Zoomist('#my-zoomist', {
  zoomer: {
    inEl: '.custom-in-zoomer',
    outEl: '.custom-out-zoomer',
    disableOnBounds: false
  }
})
{
inEl string | querySelector null String with CSS selector or querySelector of zoom in element. If set to false zoomist will create a zoom in element for you.
outEl string | querySelector null String with CSS selector or querySelector of zoom out element. If set to false zoomist will create a zoom out element for you.
disableOnBounds boolean true zoomer will be disabled when image can't be larger or smaller.
}

Methods

After you initialize Zoomist you have its initialized instance in variable with these methods. As the following example :

const myZoomist = new Zoomist('#my-zoomist')

// 
myZoomist.zoom(0.5)

All available methods :

Methods Description
zoomist.getContainerData() Get the { width, height, aspectRatio } of the container (initial-element).
zoomist.getImageData() Get the { width, height, aspectRatio, top, left, naturalWidth, naturalHeight } of the image.
zoomist.getSliderValue() Get the current value of the slider.
zoomist.getZoomRatio() Get the current value of zoom ratio.
zoomist.zoom(ratio) Zoom the image with a relative ratio.

Zoom in - requires a positive number. (ratio > 0)
Zoom out - requires a negative number. (ratio < 0)

// ex: 
zoomist.zoom(0.1)
zoomist.zoom(-0.1)
zoomist.zoomTo(ratio) Zoom the image with a absolute ratio.

Requires a positive number. (ratio > 0)

// ex: 
zoomist.zoomTo(2)
zoomist.move(x, y) Move the image with a relative position.

x or y should be a number.

// ex: 
zoomist.move(100, 100)
zoomist.move(100) // move only x position
zoomist.move(null, 100) // move only y position
zoomist.moveTo(x, y) Move the image with a absolute position.

x or y should be a number.

// ex: 
zoomist.moveTo(0, 0) // move image to top-left position
zoomist.moveTo(100) // move x to 100px, y stay the same
zoomist.moveTo(null, 100) // move y to 100px, x stay the same
zoomist.slideTo(value, isOnlySlide) Set the slider to a specific value.

If the second argument is true, zoomist will only set the slider value.

// ex: 
zoomist.slideTo(50)
zoomist.on(event, handler) Add event handler. 
// ex: 
zoomist.on('ready', function() {
  console.log('Zoomist is ready !')
})
zoomist.reset() Reset the image to initial state.
zoomist.update() The shortcut of zoomist.destroy() and zoomist.init().
zoomist.destroy() Destroy the zoomist and remove all events listeners.

Events

Zoomist provides several useful events you can listen. Events can be assigned in two ways:


1. Using on parameter before initialization.

const zoomist = new Zoomist('#my-zoomist', {
  // ...
  on: {
    ready() {
      console.log('Zoomist is ready !')
    }
  }
})

2. Using on method after initialization.

const zoomist = new Zoomist('#my-zoomist', {
  // ...
})

zoomist.on('ready', function() {
  console.log('Zoomist is ready !')
})

The keyword this within event handler always points to Zoomist instance.


All available events :

Events Arguments Description
ready () Event will fire when the zoomist instance is ready.
zoom (ratio) Event will fire when zooming.
The first argument is the ratio of the image.
wheel (event) Event will fire when wheeling.
dragStart (transform, event) Event will fire when mouse down to the image.
The first argument is the trasform value (x, y) of the image.
drag (transform, event) Event will fire when the image is dragging.
The first argument is the trasform value (x, y) of the image.
dragEnd (transform, event) Event will fire when mouse up to the image.
The first argument is the trasform value (x, y) of the image.
slideStart (value, event) Event will fire when mouse down to the slider.
The first argument is the trasform value of the slider.
slide (value, event) Event will fire when sliding the slider.
The first argument is the trasform value of the slider.
slideEnd (value, event) Event will fire when mouse up to the slider.
The first argument is the trasform value of the slider.
pinchStart (event) Event will fire when touch start with two fingers.
This event only works on mobile device.
pinch (event) Event will fire when touch move with two fingers.
This event only works on mobile device.
pinchEnd (event) Event will fire when touch end with two fingers.
This event only works on mobile device.
resize () Event will fire when zoomist is resizing.
reset () Event will fire when using reset() method.
destroy () Event will fire when using destroy() method.
update () Event will fire when using update() method.

Demo

Simple usage

{x: 0, y: 0}
<div id="my-zoomist" data-zoomist-src="./image/cats.jpg"></div>
// init
new Zoomist('#my-zoomist', {
  height: '75%'
  slider: true,
  zoomer: true
})

⚠️

This version(v1.x) has stopped updating, highly recommended to migrate to version 2.x.

Stay here
Checkout v2