medium-zoom

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

View demo 🔎

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 Element, a NodeList, an HTMLCollection or an array of images to the plugin.

// CSS selector
mediumZoom('#cover')

// Element
mediumZoom(document.getElementById('cover'))

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

// HTMLCollection
mediumZoom(document.images)

// 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.

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'
})

.detach()

Releases the images related to the zoom from the plugin.

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

zoom.detach()

Emits an event detach.

.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

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

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

Examples

mediumZoom('.post img')

mediumZoom('#cover')

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

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

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

  mediumZoom(imagesToZoom)
})

mediumZoom({
  margin: 16,
  background: '#000',
  scrollOffset: 0,
  metaClick: false
})

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

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

let counter = 0
const zoom = mediumZoom('#image-tracked')

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

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

setTimeout(() => {
  zoom.detach()
}, 5000)

Demo

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

Dev

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

Note: make sure to include the full version (not minified) of the JavaScript source in the HTML file since npm run dev doesn't build the minified version.

Contributing

Need more options? Send a pull request!

1. Fork the repository
2. Create a new branch
3. Send a pull request 👌

License

MIT © François Chalifour