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

mediumZoom(imagesToZoom) })

</details>

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

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!

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

License

MIT © François Chalifour