@lylech/react-image-magnifier

A responsive image-magnifying Javascript component for mouse and touch, with integrated thumbnail ribbon, offering carousel like functionality. Suitable for photographs, e-commerce products, etc. Authored in raw Javascript with zero dependencies, this widget is easily integrated in Angular, React (examples and documentation provided), Vue and other JS frameworks.

Click/tap on a thumbnail to select an image into the magnification pane. Move the mouse/drag a finger over the magnification pane to zoom-in on and pan to the corresponding area of the selected image.

Appearance of the widget components may be stylized via your own CSS.

Interactive Demo Site

See the following for React examples and links to sourcde code on Gitlab. https://react347.gitlab.io/lfcmagnifier/

Installation

npm install --save @lylech/react-image-magnifier

Basic Usage

You will have to, of course, provide your own images img1..img-n. This works great for images present on your system at build-time. For run-time, web based images are also supported as entries in arrayOfImagePaths.

//MyMagnifier.js
import React, { useRef, useEffect } from 'react';
import {RIMagnifier} from '@lylech/react-image-magnifier';
import img1 from "../img/img-01.jpeg";
import img2 from "../img/img-02.jpeg";
...
import img-n from "../img/img-n.jpeg";
...

export default function MyMagnifier() {
  const refMagnifier = useRef(null);

  const onThumbnailClick=(idxImage)=>{
    console.log("@ onThumbnailClick: Clicked on image# %o.", idxImage);
  };

  useEffect( ()=>{
    new RIMagnifier({
      container: refMagnifier.current,
      arrayOfImagePaths: [img1, img2, ... img-n],
      fnClickHandler: onThumbnailClick,
    });
  });
  return (
    <div className='react-image-magnifier' ref={refMagnifier} />
  )
}

Parameters/Props

Methods/Functions

Controlling the Appearance

Certain aspects of the appearance may controlled by setting the class of the container element.

The position of the Thumbnail Ribbon may be controlled by adding the appropriate class to the container(ref) element.

By default, the Thumbnail Ribbon is positioned on the bottom edge. To alter this, apply one of the following classes to the container element.

Details for the Technically Inclined

The design philosophy that drove the development of this widget:

• to offer an easy method for presenting a series of product images
• to offer an easy-to-use widget, with minimal fluff,
  • authored in plain old Javascript, it is suitable for use in class or function components
  • easily integrated into any JS frameworks
• to favour rock-solid functionality for mouse and touch enabled devices,
• to offer a full set of cosmetic customization options, or cosmetications.

In other words, that which it purports to do i.e. image magnification, it should do well, and for that which it does not do well i.e. look pretty, to allow users to cosmeticate to their heart's content.

Summary of react-image-magnifier Components:

Lean, unpretentious and authored in plain old Javascript, this widget supports a plethora of cosmetications.

Main View

The Main View is composed of two parts - the Magnification Pane and the Thumbnail Ribbon.

Magnification Pane

Move the mouse into this area to zoom-in on the selected image. Move the mouse within this area to pan the zoomed image accordingly. Move the mouse outside this area to restore the image.

For touch devices, single tap in this area to zoom-in on the selected image. Drag within this area to pan the zoomed image. Tap outside this area to restore the image.

Zoom values may be specified on a per-image basis when invoking the constructor.

Thumbnail Ribbon

Thumbnails of images available for selection are displayed in this area. Click or tap on a thumbnail to select it into the Magnification Pane.

Thumbnail images are generated automatically from the given images and sized to fit either the height or width of each thumbnail container while maintaining the original aspect ratio.

Customizing the Appearance with CSS

This section identifies the CSS classes that control the appearance of the widget components. The default behaviour may be overridden by defining more specific CSS rules e.g. in your own CSS file, precede each rule with the (class name or ID of the) container.

Main View

• CSS Class: div.lfc-rim-main
  • By default, the Main View occupies the entire width and height of its container.

Magnification Pane

• CSS Class: div.lfc-rim-product

  • By default the Magnification Pane occupies the entire width of the container and the top four-fifths height of the container.

• CSS Class: div.lfc-rim-product.selected

  • selected class is toggled when a new thumbnail is selected and is used to trigger an effect, animation or transition.

Thumbnail Ribbon

• CSS Class: lfc-rim-thumbnails
  • By default the Thumbnail Ribbon occupies entire width and the bottom fifth of the container.
  • Scrolling thumbnails within the ribbon is not presently supported.

Thumbnail Tile

• CSS Class: lfc-rim-thumbnail
  • By default a Thumbnail Tile is displayed for each provided image. In other words, the width of each tile varies according to the number of tiles required to occupy the full width of the container.
• CSS Class: lfc-rim-thumbnail.active
  • active marks the currently selected image.