leq6c/loupe-js

Image magnifier in TypeScript that works with touch events; supports React

Loupe

An image magnifier for JavaScript. Based on this Codepen.

Demo: https://nishanths.github.io/loupe-js

• Features
• Install
• Examples
  • Basic example
  • React example
  • Using script tag
• Documentation
  • Loupe
  • enableLoupe
• Recommendations

Features

• supports mouse and touch events
• customize magnification level, loupe size, loupe shape, and use custom CSS
• TypeScript type definitions
• works with React (see examples)
• proper event listener and DOM cleanup

Install

Use npm or yarn

npm i --save loupe-js

yarn add loupe-js

If you want to evaluate the package quickly without using a package manager use dist/index.window.js, which has the module's exports in window.loupe.

Remember to include the style.css file.

Examples

Basic example

Import "loupe-js" and the related CSS file.

import { Loupe, enableLoupe } from "loupe-js"
import "loupe-js/dist/style.css"

const img = document.querySelector("img")!

const options = {
	magnification: 2,
	width: 250,
	height: 250,
	additionalClassName: "customLoupeClass",
	style: { boxShadow: "4px 5px 5px 4px rgba(0,0,0,0.5)" },
	shape: "circle",
}
const loupe = new Loupe(options) // or just `new Loupe()` to use default options

enableLoupe(img, img.src, loupe)

React example

For a function component that uses hooks:

import React, { useEffect } from "react"
import { Loupe, enableLoupe } from "loupe-js"
import "loupe-js/dist/style.css"

export const MyPicture: React.SFC<{ imgUrl: string }> = ({ imgUrl }) => {
  const pictureRef = useRef<HTMLDivElement | undefined>(undefined)

  useEffect(() => {
    if (pictureRef.current !== undefined) {
      // create a loupe and add it to the target element
      const loupe = new Loupe()
      const disable = enableLoupe(pictureRef.current, imgUrl, loupe)

      // on the way out disable the loupe on the target element, and
      // remove it from the DOM
      return () => {
        disable()
        loupe.unmount()
      }
    }
  }, [pictureRef, imgUrl])

  return <div className="pic" ref={r => { pictureRef.current = r }}></div>
}

Using script tag

Import the specific script index.window.js that makes the package's exports available on the window object:

<link rel="stylesheet" href="dist/style.css">
<script src="dist/index.window.js"></script>

Then use it in your JavaScript:

const { Loupe, enableLoupe } = window.loupe
// ... use new Loupe() and enableLoupe() ...

Documentation

Loupe

The Loupe constructor constructs a loupe object.

const loupe = new Loupe(options)

Pass in an optional LoupeOptions object to the constructor to customize the loupe.

type LoupeOptions = {
	magnification?: number // magnification level
	width?: number | string // width of the loupe
	height?: number | string // height of the loupe
	container?: Node // containing node
	additionalClassName?: string // additional class name to add to the loupe element
	style?: Partial<CSSStyleDeclaration> // additional styles to add to the loupe element
	shape?: "rectangle" | "circle" // shape of the loupe
}

All propeties are optional. By default the loupe element is placed at the end of document.body. If the shape is circle you should use the same values for width and height. The additionalClassName and style properties are useful to add custom styles to the loupe element.

The default LoupeOptions values are

{
	magnification: 2.25,
	width: 250,
	height: 250 / 1.6,
	container: document.body,
	additionalClassName: undefined,
	style: undefined,
	shape: "rectangle",
}

The Loupe#unmount() method removes the loupe element from the container node in the DOM. The loupe object should not be used after.

loupe.unmount() // loupe element will no longer exist in the DOM

enableLoupe

enableLoupe() adds the specified Loupe object to the target element.

const disable = enableLoupe(target, imgUrl, loupe)

It returns a cleanup function that can be used to disable the loupe on the target element at a later time.

The target element can be, for instance, an <img> element or a <div> element with a background-image. The imgUrl is the URL to the image. For example, it is the src property for an <img> element, or background-image CSS property for a <div> element.

The type definition is:

(target: HTMLElement | SVGElement, imgUrl: string, loupe: Loupe) => (() => void)

Recommendations

Using a box-shadow on the loupe helps separate the loupe nicely from your image. For example:

new Loupe({
	style: { boxShadow: "4px 5px 5px 4px rgba(0,0,0,0.5)" },
})

License

BSD 2-Clause