medium-zoom

Medium-like zoom on your pictures in pure JavaScript 🔎🖼

Install

$ npm install --save medium-zoom

Or download the minified version.

No dependencies.

Features

🔎 Image selection — apply the zoom to a selection of images
🖱 Mouse, keyboard and gesture friendly — click anywhere, press a key or scroll away to dismiss the zoom
🎉 Event handling — triggers events when the zoom enters a new state
🔧 Customization — set your own margin, background and scroll offset
🔗 Link support — opens the link of the image in a new tab when a meta key is held (⌘ or Ctrl)
🖼 Image opener — when no link, opens the image source in a new tab when a meta key is held (⌘ or Ctrl)
📱 Responsive — scales on mobile and desktop
🚀 Performant and lightweight — should be able to reach 60 fps

Usage

1. Import the script

<script src="node_modules/medium-zoom/dist/medium-zoom.min.js"></script>

Or:

const mediumZoom = require('medium-zoom')

2. Run the plugin

mediumZoom(<selector>, <options>)

By default, the zoom is applied to all scaled images (with HTML or CSS properties). You can specify the zoomable images with a CSS selector and add options.

Additionally, you can pass an array-like or an array of images to the plugin.

// CSS selector
mediumZoom('#cover')

// array-like
mediumZoom(document.querySelectorAll('[data-action="zoom"]'))

// array
const imagesToZoom = [
  document.querySelector('#cover'),
  ...document.querySelectorAll('[data-action="zoom"]')
]

mediumZoom(imagesToZoom)

API

Options

Options can be passed via a JavaScript object through the mediumZoom call.

Properties	Type	Default	Description
margin	integer	`0`	Space outside the zoomed image
background	string	`"#fff"`	Color of the overlay
scrollOffset	integer	`48`	Number of pixels to scroll to dismiss the zoom
metaClick	boolean	`true`	Enables the action on meta click (opens the link / image source)

mediumZoom('[data-action="zoom"]', {
  margin: 24,
  background: '#000',
  scrollOffset: 0,
  metaClick: false
})

Methods

`.show()`

Triggers the zoom.

const zoom = mediumZoom('#my-image')

zoom.show()

Emits an event show on animation start and shown when completed.

`.hide()`

Dismisses the zoom.

const zoom = mediumZoom('#my-image')

zoom.hide()

Emits an event hide on animation start and hidden when completed.

`.toggle()`

Shows the zoom when hidden, hides the zoom when shown.

const zoom = mediumZoom('#my-image')

zoom.toggle()

`.update(<options>)`

Updates and returns the options.

const zoom = mediumZoom('#my-image')

zoom.update({
  background: '#000'
})

`.addEventListeners(type, listener)`

Registers the specified listener on each target of the zoom.

const zoom = mediumZoom('[data-action="zoom"]')

zoom.addEventListeners('hidden', () => {
  // do something...
})

Events

Event	Description
show	Fired immediately when the `show` instance method is called
shown	Fired when the zoom has finished being animated
hide	Fired immediately when the `hide` instance method is called
hidden	Fired when the zoom out has finished being animated

const zoom = mediumZoom('#image-tracked')

zoom.addEventListeners('show', event => {
  // do something...
})

Examples

Images in post content

```js mediumZoom('.post img') ```

One image by `id`

```js mediumZoom('#cover') ```

Images with `data` attribute

```js mediumZoom('[data-action="zoom"]') ```

External images

```js mediumZoom('img[src^="http"]') ```

Images from a database

```js fetch('https://myapi.com/posts/{id}', { method: 'GET' }) .then(response => { const imagesToZoom = response.images .map(imgSrc => document.querySelector(`img[src=${imgSrc}]`))

mediumZoom(imagesToZoom) })

</details>

<details>
 <summary>Margins, overlay, scroll offset and click</summary>
```js
mediumZoom({
  margin: 16,
  background: '#000',
  scrollOffset: 0,
  metaClick: false
})

Trigger the zoom dynamically

```js const button = document.querySelector('#btn-zoom') const zoom = mediumZoom('#image')

button.addEventListener('click', () => zoom.show())

</details>

<details>
 <summary>Zoom counter</summary>
```js
let counter = 0
const zoom = mediumZoom('#image-tracked')

zoom.addEventListeners('show', event => {
  console.log(`"${event.target.alt}" has been zoomed ${++counter} times`)
})

Demo

View demo 🔎, go to the demo folder or read the article.

Dev

Install the dependencies: npm install
Watch changes: npm run dev

Contributing

Need more options? Send a pull request!

mrdream24/medium-zoom