medium-zoom

A JavaScript library for zooming images like Medium

🔬 Playground ・ 🔎 Demo ・ 📚 Storybook

` Opens the zoom and returns a promise resolving with the zoom. ```js const zoom = mediumZoom('[data-zoomable]') zoom.open() ``` _Emits an event [`open`](#events) on animation start and [`opened`](#events) when completed._ #### `close(): Promise` Closes the zoom and returns a promise resolving with the zoom. ```js const zoom = mediumZoom('[data-zoomable]') zoom.close() ``` _Emits an event [`close`](#events) on animation start and [`closed`](#events) when completed._ #### `toggle({ target?: HTMLElement }): Promise` Opens the zoom when closed / dismisses the zoom when opened, and returns a promise resolving with the zoom. ```js const zoom = mediumZoom('[data-zoomable]') zoom.toggle() ``` #### `attach(...selectors: string[] | HTMLElement[] | NodeList[] | Array[]): Zoom` Attaches the images to the zoom and returns the zoom. ```js const zoom = mediumZoom() zoom.attach('#image-1', '#image-2') zoom.attach( document.querySelector('#image-3'), document.querySelectorAll('[data-zoomable]') ) ``` #### `detach(...selectors: string[] | HTMLElement[] | NodeList[] | Array[]): Zoom` Releases the images from the zoom and returns the zoom. ```js const zoom = mediumZoom('[data-zoomable]') zoom.detach('#image-1', document.querySelector('#image-2')) // detach two images zoom.detach() // detach all images ``` _Emits an event [`detach`](#events) on the image._ #### `update(options: object): Zoom` Updates the options and returns the zoom. ```js const zoom = mediumZoom('[data-zoomable]') zoom.update({ background: '#BADA55' }) ``` _Emits an event [`update`](#events) on each image of the zoom._ #### `clone(options?: object): Zoom` Clones the zoom with provided options merged with the current ones and returns the zoom. ```js const zoom = mediumZoom('[data-zoomable]', { background: '#BADA55' }) const clonedZoom = zoom.clone({ margin: 48 }) clonedZoom.getOptions() // => { background: '#BADA55', margin: 48, ... } ``` #### `on(type: string, listener: () => void, options?: boolean | AddEventListenerOptions): Zoom` Registers the listener on each target of the zoom. The same `options` as [`addEventListener`](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener#Parameters) are used. ```js const zoom = mediumZoom('[data-zoomable]') zoom.on('closed', event => { // the image has been closed }) zoom.on( 'open', event => { // the image has been opened (tracked only once) }, { once: true } ) ``` The zoom object is accessible in `event.detail.zoom`. #### `off(type: string, listener: () => void, options?: boolean | AddEventListenerOptions): Zoom` Removes the previously registered listener on each target of the zoom. The same `options` as [`removeEventListener`](https://developer.mozilla.org/docs/Web/API/EventTarget/removeEventListener#Parameters) are used. ```js const zoom = mediumZoom('[data-zoomable]') function listener(event) { // ... } zoom.on('open', listener) // ... zoom.off('open', listener) ``` The zoom object is accessible in `event.detail.zoom`. #### `getOptions(): object` Returns the zoom options as an object. ```js const zoom = mediumZoom({ background: '#BADA55' }) zoom.getOptions() // => { background: '#BADA55', ... } ``` #### `getImages(): HTMLElement[]` Returns the images attached to the zoom as an array of [`HTMLElement`s](https://developer.mozilla.org/docs/Web/API/HTMLElement). ```js const zoom = mediumZoom('[data-zoomable]') zoom.getImages() // => [HTMLElement, HTMLElement] ``` #### `getZoomedImage(): HTMLElement` Returns the current zoomed image as an [`HTMLElement`](https://developer.mozilla.org/docs/Web/API/HTMLElement) or `null` if none. ```js const zoom = mediumZoom('[data-zoomable]') zoom.getZoomedImage() // => null zoom.open().then(() => { zoom.getZoomedImage() // => HTMLElement }) ``` ### Attributes #### `data-zoom-src` Specifies the high definition image to open on zoom. This image loads when the user clicks on the source image. ```html ``` ### Events | Event | Description | | ------ | --------------------------------------------------- | | open | Fired immediately when the `open` method is called | | opened | Fired when the zoom has finished being animated | | close | Fired immediately when the `close` method is called | | closed | Fired when the zoom out has finished being animated | | detach | Fired when the `detach` method is called | | update | Fired when the `update` method is called | ```js const zoom = mediumZoom('[data-zoomable]') zoom.on('open', event => { // track when the image is zoomed }) ``` The zoom object is accessible in `event.detail.zoom`. ## Framework integrations Medium Zoom is a JavaScript library that can be used with any framework. Here are some integrations that you can use to get started quickly: - [React](./examples/react) - [React Markdown](./examples/react-markdown) - [Vue](./examples/vue) - [Svelte](./examples/svelte) ## Examples

Trigger a zoom from another element

```js const button = document.querySelector('[data-action="zoom"]') const zoom = mediumZoom('#image') button.addEventListener('click', () => zoom.open()) ```

Track an event (for analytics)

You can use the `open` event to keep track of how many times a user interacts with your image. This can be useful if you want to gather some analytics on user engagement. ```js let counter = 0 const zoom = mediumZoom('#image-tracked') zoom.on('open', event => { console.log(`"${event.target.alt}" has been zoomed ${++counter} times`) }) ```

Detach a zoom once closed

```js const zoom = mediumZoom('[data-zoomable]') zoom.on('closed', () => zoom.detach(), { once: true }) ```

Attach jQuery elements

jQuery elements are compatible with `medium-zoom` once converted to an array. ```js mediumZoom($('[data-zoomable]').toArray()) ```

Create a zoomable React component

```js import React, { useRef } from 'react' import mediumZoom from 'medium-zoom' export function ImageZoom({ options, ...props }) { const zoomRef = useRef(null) function getZoom() { if (zoomRef.current === null) { zoomRef.current = mediumZoom(options) } return zoomRef.current } function attachZoom(image) { const zoom = getZoom() if (image) { zoom.attach(image) } else { zoom.detach() } } return } ```

You can see [more examples](examples/) including [React](examples/react) and [Vue](examples/vue), or check out the [storybook](https://medium-zoom.francoischalifour.com/storybook). ## Debugging ### The zoomed image is not visible The library doesn't provide a `z-index` value on the zoomed image to avoid conflicts with other frameworks. Some frameworks might specify a `z-index` for their elements, which makes the zoomed image not visible. If that's the case, you can provide a `z-index` value in your CSS: ```css .medium-zoom-overlay, .medium-zoom-image--opened { z-index: 999; } ``` ## Browser support | IE | Edge | Chrome | Firefox | Safari | | --------------- | --------------- | ------ | ------- | ------ | | 10^\* | 12^\* | 36 | 34 | 9 | ^\* _These browsers require a [`template` polyfill](https://github.com/webcomponents/template) when using [custom templates](docs/template.md)_.

Cross-browser testing is sponsored by

## Contributing - Run `yarn` to install Node dev dependencies - Run `yarn start` to build the library in watch mode - Run `yarn run storybook` to see your changes at http://localhost:9001 Please read the [contributing guidelines](CONTRIBUTING.md) for more detailed explanations. _You can also use [npm](https://www.npmjs.com)._ ## License MIT © [François Chalifour](https://francoischalifour.com)