Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Magnifier
✓ import Magnifier from 'react-magnifier';
✗ 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)
✓ const Magnifier = require('react-magnifier').default;
✗ const Magnifier = require('react-magnifier');
While primarily an ESM library, CommonJS users must access the `.default` property for the default export.
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>
);
}
Debug
Known issues
breakingVersion 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.fixReview existing code for type-related errors or implicit dependencies on internal implementation details. Ensure your build pipeline supports TypeScript if consuming types.
affects: >=3.0.0
breakingVersion 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.fixTest 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.
affects: >=2.0.0
gotchaThe `src` prop is required for the `Magnifier` component to render an image. Omitting it will lead to runtime errors or a non-functional component.fixAlways provide a valid image URL or path to the `src` prop. For example: `<Magnifier src={yourImagePath} />`. affects: >=1.0.0
gotchaThe 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.fixEnsure your project's `react` and `react-dom` dependencies are at version `16.0.0` or higher to satisfy the peer dependency requirements.
affects: <16.0.0 of React
gotchaBetween 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.fixUpgrade 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.
affects: >=3.0.0 <3.0.3
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'defaultProps')
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.
fixUpgrade `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.
Warning: Failed prop type: The prop `src` is marked as required in `Magnifier`, but its value is `undefined`.
The `src` prop, which specifies the URL or path of the image to be magnified, was not provided to the `Magnifier` component.
fixEnsure 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: Invalid hook call. Hooks can only be called inside of the body of a function component. (If using older React versions)
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.
fixVerify 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.
Audit
Dependencies
reactrequiredPeer dependency for the React component framework.