Getting Started
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.
|
|
{ | |||
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.
|
|
{ | |||
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)
|
zoomist.zoomTo(ratio) | Zoom the image with a absolute ratio. Requires a positive number. (ratio > 0)
|
zoomist.move(x, y) | Move the image with a relative position. x or y should be a number.
|
zoomist.moveTo(x, y) | Move the image with a absolute position. x or y should be a number.
|
zoomist.slideTo(value, isOnlySlide) | Set the slider to a specific value. If the second argument is true, zoomist will only set the slider value.
|
zoomist.on(event, handler) | Add event handler.
|
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
⚠️
This version(v1.x) has stopped updating, highly recommended to migrate to version 2.x.