zoom.js

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:

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  { 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 `` 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.