React Magnifier Component

3.0.4 verified Sat Apr 25 auth: no javascript

react-magnifier is a lightweight React component designed to provide interactive image zooming functionality, allowing users to magnify specific areas of an image. It is currently stable at version 3.0.4, with recent releases focusing on bug fixes, TypeScript migration, and broad browser compatibility (targeting ES3 since v3.0.4). The library exhibits a moderate release cadence, addressing issues and introducing enhancements as needed. Key differentiators include built-in support for touch screens, the ability to specify a separate, higher-resolution image for the magnified view (e.g., a thumbnail and a full-size image), and extensive customization options for the magnifying glass's appearance, shape, and behavior through props such as `zoomFactor`, `mgShape`, and `mgShowOverflow`. It functions as a pure presentation component, requiring React v16.0.0 or higher as a peer dependency.

Common errors

error TypeError: Cannot read properties of undefined (reading 'defaultProps') ↓

cause This error, particularly related to `zoomImgSrc`, occurred in `react-magnifier` versions 3.0.0 to 3.0.2 due to a missing default for the prop's type definition.

fix

Upgrade react-magnifier to version 3.0.3 or higher. If upgrading is not immediately possible, explicitly pass a value (even an empty string) for zoomImgSrc or ensure your TypeScript configuration handles optional properties correctly.

error Warning: Failed prop type: The prop `src` is marked as required in `Magnifier`, but its value is `undefined`. ↓

cause The `src` prop, which specifies the URL or path of the image to be magnified, was not provided to the `Magnifier` component.

fix

Ensure that a valid string path or URL is always passed to the src prop of the Magnifier component. Example: <Magnifier src="/images/my-product.jpg" />.

error Error: Invalid hook call. Hooks can only be called inside of the body of a function component. (If using older React versions) ↓

cause This error typically occurs if `react-magnifier` (which is a functional component using React Hooks) is used with a React version older than 16.8, or if there's a misconfiguration in the React environment causing multiple copies of React.

fix

Verify that your project's react and react-dom dependencies are at version 16.8.0 or higher. Also, check for potential issues with npm link or multiple installations of React that can cause the 'Invalid hook call' error.

Warnings

breaking Version 3.0.0 migrated the codebase to TypeScript. While generally an improvement, this could introduce subtle breaking changes for consumers relying on previous internal module structures or type declarations if manually managed. It also fixed issues with event listener removal. ↓

fix Review existing code for type-related errors or implicit dependencies on internal implementation details. Ensure your build pipeline supports TypeScript if consuming types.

breaking Version 2.0.0 introduced significant changes to the magnifying behavior, particularly close to the image borders. This may result in different glass positioning or cropping compared to prior versions. New props like `mgShowOverflow` and `borderWidth` were also added, potentially altering default visual characteristics. ↓

fix Test your application's image zoom functionality thoroughly after upgrading. Adjust `mgShowOverflow`, `mgMouseOffsetX`, `mgMouseOffsetY`, and other related props to match desired behavior, especially if migrating from pre-v2.0.0 versions.

gotcha The `src` prop is required for the `Magnifier` component to render an image. Omitting it will lead to runtime errors or a non-functional component. ↓

fix Always provide a valid image URL or path to the `src` prop. For example: `<Magnifier src={yourImagePath} />`.

gotcha The package lists `react: "^16.0.0"` as a peer dependency. Using `react-magnifier` with older versions of React may lead to peer dependency warnings or runtime issues, especially related to Hooks which were introduced in React 16.8. ↓

fix Ensure your project's `react` and `react-dom` dependencies are at version `16.0.0` or higher to satisfy the peer dependency requirements.

gotcha Between versions 3.0.0 and 3.0.2, TypeScript users might have encountered a type error related to the `zoomImgSrc` prop, specifically a missing default or incorrect type definition, leading to compilation failures. ↓

fix Upgrade to `react-magnifier@3.0.3` or newer to resolve the `zoomImgSrc` type definition issue. If unable to upgrade, you may need to explicitly define `zoomImgSrc` or assert its type.

Install

npm install react-magnifier

yarn add react-magnifier

pnpm add react-magnifier

Imports

Magnifier

wrong

import { Magnifier } from 'react-magnifier';

correct

import Magnifier from 'react-magnifier';

This component is exported as a default export.

MagnifierProps
```
import type { MagnifierProps } from 'react-magnifier';
```
For TypeScript users, import prop types from the package.
Magnifier (CJS)
wrong
```
const Magnifier = require('react-magnifier');
```
correct
```
const Magnifier = require('react-magnifier').default;
```
While primarily an ESM library, CommonJS users must access the `.default` property for the default export.

Quickstart

This quickstart demonstrates how to integrate the Magnifier component, showcasing basic image zoom functionality using separate source images for the thumbnail and the zoomed view, along with common customization props like `zoomFactor` and `mgShape`.

import Magnifier from 'react-magnifier';
import yourImage from './path/to/your-high-res-image.jpg';
import yourThumbnail from './path/to/your-thumbnail.jpg';

export default function ImageZoomComponent() {
  return (
    <div style={{ width: '80%', margin: '20px auto' }}>
      <h1>Product Image Viewer</h1>
      <p>Hover or touch the image to magnify.</p>
      <Magnifier
        src={yourThumbnail}
        zoomImgSrc={yourImage}
        width={600}
        height={400}
        zoomFactor={2.5}
        mgWidth={200}
        mgHeight={200}
        mgShape="square"
        alt="Product showcase with zoom"
      />
      <p>The `src` prop displays the initial image, and `zoomImgSrc` provides a higher-resolution image for the magnifying glass. If `zoomImgSrc` is omitted, `src` will be used for both.</p>
    </div>
  );
}