HOVER THIS ☝

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

#### 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/gh/cotton123236/zoomist@latest/dist/zoomist.min.css"/>

    <script src="https://cdn.jsdelivr.net/gh/cotton123236/zoomist@latest/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

Demo HTML JS

{x: 0, y: 0}

- fill
- draggable
- wheelable
- pinchable
- bounds
- zoomRatio
- maxRatio
- slider.direction
- zoomer.disableOnBounds

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

    // init
    new Zoomist('#my-zoomist', {
      height: '75%'
      slider: true,
      zoomer: true
    })