zoomist

Zoomist is TypeScript library for zooming any element. Also supports mobile devices.

Documentation | Demo

🚀 Installation

There are few ways to import Zoomist into your project:

Install from NPM

You can easily install Zoomist from NPM.

npm i zoomist

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

// initialize
const zoomist = new Zoomist(...)

Using CDN

There are two ways to include Zoomist by using CDN.

UMD:

<!-- styles -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/zoomist@2/zoomist.css" />

<!-- scripts -->
<script src="https://cdn.jsdelivr.net/npm/zoomist@2/zoomist.umd.js"></script>
<script>
  const zoomist = new Zoomist(...)
</script>

ES modules in browser:

<!-- styles -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/zoomist@2/zoomist.css" />

<!-- scripts -->
<script type="module">
  import Zoomist from 'https://cdn.jsdelivr.net/npm/zoomist@2/zoomist.js'

  const zoomist = new Zoomist(...)
</script>

Download assets

Or you can use Zoomist locally by DOWNLOAD assets.

📝 Basic usage

After downloading Zoomist, there are a few steps to create a Zoomist:

Add Zoomist HTML layout

You need to add Zoomist layout in your HTML:

<!-- 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>

Custom Zoomist styles

You may want to add some 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;
}

Initialize Zoomist

Finally, initialize Zoomist in your js file:

const zoomist = new Zoomist('.zoomist-container', {
  // Optional parameters
  maxScale: 4,
  bounds: true,
  // if you need slider
  slider: true,
  // if you need zoomer
  zoomer: true
})

📖 Documentation

Parameters

All available parameters and initial value:

new Zoomist('.zoomist-container', {
  // 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: '.zoomist-not-draggable',
  // elements matched this class will not be zoomed by mouse wheel.
  disableWheelingClass: '.zoomist-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'
  }
})

Methods

All available methods:

const zoomist = new Zoomist(...)

zoomist.zoom(ratio)
zoomist.zoomTo(ratio)
zoomist.move({ x, y })
zoomist.moveTo({ x, y })
zoomist.slideTo(value)
zoomist.reset()
zoomist.update(options)
zoomist.destroy(cleanStyle)
zoomist.destroySlider()
zoomist.destroyZoomer()
zoomist.destroyModules()

zoomist.on(event, handler)

zoomist.getImageData()
zoomist.getContainerData()
zoomist.getSliderValue()

zoomist.isOnBoundX()
zoomist.isOnBoundY()
zoomist.isOnBoundTop()
zoomist.isOnBoundBottom()
zoomist.isOnBoundLeft()
zoomist.isOnBoundRight()
zoomist.isOnMinScale()
zoomist.isOnMaxScale()

Events

// Using on parameter before initialization.
const zoomist = new Zoomist('.zoomist-container', {
  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) {...}
  }
})

// Using on method after initialization.
// For example:
zoomist.on('zoom', (zoomist, scale) => {...})

Changelog

[2.2.0] - 2024-03-16

New Features

• Add smooth option for smoother dragging experience.

Patch

• Fix ShadowRoot support