medium-zoom

Medium-like zoom on your pictures in pure 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 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'
})

.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

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
detach	Fired when the detach instance method is called

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

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

Examples

Images in post content

mediumZoom('.post img')

One image by `id`

mediumZoom('#cover')

Images with `data` attribute

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

External images

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

Images from a database

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

  mediumZoom(imagesToZoom)
})

Margins, overlay, scroll offset and click

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

Trigger the zoom dynamically

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

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

Zoom counter

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

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

Detach the zoom after a while

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