yet-another-medium-zoom

Yet Another Medium Zoom

YAMZ is a lightbox library heavily inspired by Medium.

It provides an easy way to add smooth, minimalistic, and highly customizable Medium-like zooming to your images.

Usage

To use the library, you simply tell it which images to bind to:

import yamz from "yet-another-medium-zoom";

const $images = [...document.querySelectorAll("img, picture")];
yamz.bind($images);

That's it. The library will automatically extract the appropriate high-res source from your images if you are using srcset, and will otherwise just use the image's own source (or a high-res source you specify).

Configuration

If you want to have more control over what's displayed, you may want to change some of the options. You can set an option globally, or you can specify the options on a per-image basis. This can be done in JavaScript when you open the lightbox, or in HTML by specifying the options on the image you bind to as data attributes.

<!-- set the options as data attributes -->
<img src="example.png" data-scroll-allowance="-1" data-duration="600" />

/* or specify them when you open the lightbox programmatically */
import yamz from "yet-another-medium-zoom";

yamz.setOptions({
    // set options globally
    /* ... */
});
const $img = document.querySelector("img");
yamz.open($img, {
    // set options on a per-image basis
    /* ... */
});

The following options are available:

Name	Data attribute	Type	Default value	Description
scrollAllowance	data-scroll-allowance	number	128	How much the user can scroll before the lightbox is closed. -1 to disable
duration	data-duration	number	300	How long the animation should take, measured in milliseconds
container	None	HTMLElement	document.body	The element to render the lightbox inside
class	data-class	string	null	Class to give to the lightbox element. Mostly useful for styling
highres	data-highres	string	null	URL of the high-res image to load. Can't be set globally
caption	data-caption	string | HTMLElement	null	String or element to insert as a caption below the image. Can't be set globally
album	data-album	{ img: HTMLElement, opts?: {} }[]	null	If set, the album that an image belongs to. Can be specified in HTML by using a string - all images with the same album string will then be considered part of the album. Can't be set globally
wrapAlbum	None	boolean	false	Whether to wrap albums, so you can press left on the first image to go to the last one, and vice versa
lightboxGenerator	None	(img: HTMLElement, opts: ImageOptions) => HTMLElement	null	Function which generates the lightbox, if you want to use a custom one. See below for more information

Advanced Customization

There are two main ways to perform more in-depth customization of the lightbox:

CSS / DOM customization

You can style the lightbox however you want by simply using CSS to overwrite the built-in styles. You can also change the DOM structure of the lightbox by using the lightboxGenerator option, which lets you completely change what the lightbox contains. You can see an example of this on the project website. The animation will automatically adapt to your new styles.

Plugins

Plugins can be created if you need more advanced control. These are implemented as functions that augment a given YAMZ instance with whatever features the plugin implements. These plugins can then be composited if you want to use more than one at a time. An example of this can be seen in our main export.

Both the caption and album support are actually implemented as plugins (that are enabled by default), so if you want to create your own plugin it might be useful to reference the implementation of the caption or album plugins.