medium-zoom

library1.1.0jsnpmunverified

Medium Zoom is a lightweight, responsive JavaScript library designed to replicate the elegant image zooming experience found on the Medium platform. Currently stable at version 1.1.0, the package sees active development with regular patch releases addressing bugs and minor enhancements, building upon its significant 1.0.0 refactor. Key differentiators include its high performance (aiming for 60fps), support for high-definition image loading on zoom, extensive customization options for margin, background, and scroll offset, and a pluggable architecture allowing for custom features and templates. It is framework-agnostic, working seamlessly across React, Vue, Angular, Svelte, and Solid, and offers comprehensive event handling for various zoom states. The library focuses on providing a smooth, intuitive user experience that is friendly to mouse, keyboard, and touch gestures.

web-framework

npm install medium-zoom

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MEDIUM-ZOOM

medium-zoom

web-frameworkjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mediumZoom

✓ import mediumZoom from 'medium-zoom';

✗ const mediumZoom = require('medium-zoom');

The library primarily uses a default export for the main function. While CommonJS `require` might work in some transpiled environments, native ESM import is preferred. Since v1.0.0, the package is built with modern JS targets in mind.

Zoom / Options (TypeScript Types)

✓ import type { Zoom, Options } from 'medium-zoom';

These types are useful for explicit type declarations when working with the zoom instance or its configuration options in TypeScript.

CSS Styles

✓ import 'medium-zoom/dist/medium-zoom.css';

✗ import 'medium-zoom/medium-zoom.css';

The core CSS is not automatically bundled with the JavaScript and must be imported separately to ensure the zoom animation and overlay are styled correctly. For v1.1.0+, a `medium-zoom.pure.css` bundle is also available, separating JS and CSS further.

This code initializes `mediumZoom` on elements matching a CSS selector, demonstrates attaching additional elements, sets custom options, and logs events during the zoom lifecycle. It also includes the necessary CSS import.

import mediumZoom from 'medium-zoom'; import 'medium-zoom/dist/medium-zoom.css'; document.addEventListener('DOMContentLoaded', () => { // Initialize mediumZoom on all images with the class 'zoomable-image' const zoom = mediumZoom('.zoomable-image', { margin: 24, // Space between the image and the edge of the viewport background: 'rgba(0, 0, 0, 0.8)', // Dark overlay background scrollOffset: 40 // Scroll offset to close the zoom }); // Attach additional images or selectors dynamically zoom.attach('#another-zoomable-image'); // Listen for events: 'open', 'opened', 'close', 'closed' zoom.on('open', (event) => { console.log('Zoom effect starting for:', event.target); // You can update options after the zoom is opened zoom.update({ background: 'rgba(25, 18, 25, 0.95)' }); }); zoom.on('closed', () => { console.log('Zoom effect finished closing.'); }); // Example of programmatic open (returns a Promise since v1.0.0) // document.getElementById('open-btn')?.addEventListener('click', async () => { // await zoom.open(document.querySelector('.zoomable-image')); // console.log('Programmatic zoom opened.'); // }); }); // To make this code runnable, ensure your HTML contains: // <img class="zoomable-image" src="https://picsum.photos/id/1018/400/300" alt="Forest road" /> // <img id="another-zoomable-image" src="https://picsum.photos/id/1025/400/300" alt="Pug dog" />

Debug

Known issues

breakingVersion 1.0.0 introduced significant changes where most methods (excluding getters and animation methods) became chainable, and animation methods (`open()`, `close()`, `toggle()`) now return Promises. This may break existing code relying on previous return values or synchronous animation flow.

fix

Review calls to `mediumZoom` methods. For animation methods, use `async/await` or `.then()` to handle their completion. For other methods, adjust chaining as needed.

affects: >=1.0.0 <1.1.0

gotchaThe CSS styles for medium-zoom are not automatically included with the JavaScript. Failing to import the CSS will result in an unstyled zoom overlay and animations, making the feature appear broken or incomplete.

fix

Ensure you explicitly import the CSS file: `import 'medium-zoom/dist/medium-zoom.css';` in your entry point, or link it via a `<link>` tag in your HTML. Since v1.1.0, a `medium-zoom.pure.css` bundle is also available.

affects: >=0.1.0

gotchaEarlier versions of medium-zoom (prior to 1.0.4) had limited or no compatibility with Server-Side Rendering (SSR) environments due to direct use of browser-specific `window` objects. This could lead to build failures or runtime errors in SSR frameworks.

fix

Upgrade to `medium-zoom@1.0.4` or newer. If stuck on older versions, implement conditional rendering or client-side mounting for the zoom functionality within your SSR application.

affects: <1.0.4

Errors

Common errors & fixes

Uncaught TypeError: mediumZoom is not a function

Incorrect import statement or using CommonJS `require` when an ES module environment expects `import`.

fix

Ensure you are using `import mediumZoom from 'medium-zoom';` for ESM setups. If using CommonJS, ensure your build pipeline correctly handles the module export.

TypeError: Cannot read properties of null (reading 'style')

The `mediumZoom` function was called with a selector that did not match any elements in the DOM, or the elements were not yet available when the script ran.

fix

Verify your CSS selector is correct and matches existing `<img>` elements. Wrap your `mediumZoom` initialization in a `DOMContentLoaded` listener or defer it until your images are present in the DOM.

Zoom effect doesn't appear or the overlay is unstyled

The required CSS stylesheet for medium-zoom was not loaded or imported.

fix

Add `import 'medium-zoom/dist/medium-zoom.css';` to your main JavaScript/TypeScript file or include a `<link>` tag for the CSS in your HTML.

Images dynamically added to the DOM are not zoomable.

The `mediumZoom` function was initialized before the dynamic images existed, and the zoom instance was not updated to include them.

fix

After dynamically adding new images, use the `zoom.attach(selector)` method on your existing `mediumZoom` instance to make the new images zoomable.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/francoischalifour/medium-zoom ↗

packagehttps://www.npmjs.com/package/medium-zoom ↗

homepagehttps://francoischalifour.com/medium-zoom ↗