Medium Zoom

Common errors

• Uncaught TypeError: mediumZoom is not a function

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

  cause 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

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

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

Warnings

• breaking Version 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.
• gotcha The 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.
• gotcha Earlier 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.

Install

• npm install medium-zoom npm
• yarn add medium-zoom yarn
• pnpm add medium-zoom pnpm

Imports

• mediumZoom
  wrong:

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

  correct:

  import mediumZoom from '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
  wrong:

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

  correct:

  import 'medium-zoom/dist/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.

Quickstart

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