zoom.js

An image zooming plugin, as seen on older versions of medium.com. This project is a port of fat/zoom.js but has no jQuery or Bootstrap dependencies.

Version 4 is written in TypeScript, has a new API, includes typings, and has no dependencies.

npm package: https://www.npmjs.com/package/@nishanths/zoom.js

Branches

• v4: The default branch. It contains code for version 4, which is the current major version.
• master: Frozen and no longer maintained. The final version on this branch is 3.1.0.

No API backwards compatibility guarantees even within the same major version, so, if necessary, pin an exact version and upgrade manually.

Demo

https://nishanths.github.io/zoom.js

Zoom on an image by clicking on it.

Dismiss the zoom by either clicking again on the image, clicking the overlay around the image, scrolling away, or hitting the esc key.

Usage

Install the package:

npm i @nishanths/zoom.js

Link the src/zoom.css file in your application:

<link href="zoom.css" rel="stylesheet">

Import and use symbols from the package:

import { zoom } from "@nishanths/zoom.js"

The js files in the dist directory are ES modules.

Note that the package.json for the package specifies the module property but not the main property. You may need a module-aware tool to correctly include the package in your bundle. For further reading, see this Stack Overflow answer as a starting point.

Building locally

To build the package locally, clone the repo, then run the following from the root directory:

% make deps
% make build

This should write files into the dist directory.

Documentation

API

// Config is the configuration provided to the zoom function.
export type Config = {
	// padding defines the horizontal space and the vertical space around
	// the zoomed image.
	padding: number

	// paddingNarrow is similar to the padding property, except that it is
	// used if the viewport width is too narrow, such that the use of the
	// larger padding property may produce poor results.
	//
	// paddingNarrow should be <= padding, however this is not validated.
	paddingNarrow: number

	// dismissScrollDelta defines the vertical scrolling threshold at which
	// the zoomed image is dismissed by user interaction. The value is the
	// pixel difference between the original vertical scroll position and
	// the subsequent vertical scroll positions.
	dismissScrollDelta: number

	// dismissTouchDelta defines the vertical touch movement threshold at
	// which the zoomed image is dismissed by user interaction. The value is
	// the pixel difference between the initial vertical touch position and
	// subsequent vertical touch movements.
	dismissTouchDelta: number
}

// zoom zooms the specified image.
//
// The image will not be zoomed if its naturalWidth or naturalHeight property
// is 0 (usually because the values are unavailable).
export function zoom(img: HTMLImageElement, cfg: Config = defaultConfig): void

// dismissZoom programmatically dismisses the presently active zoom. It is a
// no-op if there is no zoom active at the time of the call.
export function dismissZoom(): void

Examples

The following TypeScript program makes all existing <img> elements on the page zoomable. Images are zoomed when they are clicked.

import { zoom } from "@nishanths/zoom.js"

function setup(img: HTMLImageElement) {
	img.classList.add("zoom-cursor") // use "cursor: zoom-in" style on hover
	img.addEventListener("click", () => { zoom(img) })
}

const imgs = [...document.querySelectorAll("img")]
imgs.forEach(img => { setup(img) })

The following TypeScript program customizes only certain properties of a Config, keeping the defaults for the other properties.

import { Config, defaultConfig } from "@nishanths/zoom.js"

const customConfig: Config = {
	...defaultConfig,
	padding: 30,
}

Notes

All CSS class names used by the package are prefixed with zoom-.

Add the class name zoom-cursor to a zoomable <img> element to use an zoom-in cursor instead of the default cursor for the image.

The program appends the DOM node for the overlay element, which appears when an image is zoomed, to the end of document.body.

While an image is zoomed, the program listens for click events on document.body with useCapture set to true, and the handler function calls e.stopPropagation(). This may interfere with other click event handlers on the page. The event listener is removed when the zoom is dismissed.

When an image is zoomed, its transform style is replaced with a new value that is necessary for zooming. The old transform is restored when the zoom is dismissed.

Browser compatibility

Popular web browser versions released after 2016 should be supported by this package. Please read the source code for exact details.

License

The software in this repository is based on the original fat/zoom.js project. The copyright notices and license notices from the original project are present in the LICENSE.original file at the root of this repository.

New source code and modifications in this repository are licensed under an MIT license. See the LICENSE file at the root of the repository.