loupe-js
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    Loupe

    An image magnifier for JavaScript. Based on this Codepen.

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

    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
    Screen-Shot-2020-05-17-at-6-46-48-PM

    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

    Keywords

    none

    Install

    npm i loupe-js

    DownloadsWeekly Downloads

    4

    Version

    2.0.0

    License

    BSD-2-Clause

    Unpacked Size

    67.2 kB

    Total Files

    14

    Last publish

    Collaborators

    • nishanths