Hover Image Magnifier

A React component for magnifying images on hover with preview and magnifier modes. This package provides a smooth, interactive way to zoom and preview images when users hover over them.

⚠️ Note: This package is actively under development. Current version: 0.1.0

Installation

npm install hover-image-magnifier

or

yarn add hover-image-magnifier

or

pnpm add hover-image-magnifier

Peer Dependencies

This package requires React 18.0.0 or higher:

npm install react@^18.0.0 react-dom@^18.0.0

Basic Usage

import { HoverImageMagnifier } from "hover-image-magnifier";

function App() {
  return (
    <HoverImageMagnifier
      src="/path/to/your/image.jpg"
      alt="Description of image"
    />
  );
}

Features

• 🖼️ Two modes: Preview mode and Magnifier mode
• 📍 Smart positioning: Automatically adjusts placement to stay within viewport
• 🎨 Customizable: Full control over styling and dimensions
• ⚡ Performance: Optimized with React hooks and efficient rendering
• 📱 Responsive: Works seamlessly across different screen sizes

API Reference

Props

| Prop | Type | Default | Description | | ---------------- | ---------------------------------------------- | ------------- | ------------------------------------------------------------------- | | src | string | required | The source URL of the image to display | | alt | string | - | Alternative text for the image | | mode | "preview" \| "magnifier" | "magnifier" | Display mode: preview shows full image, magnifier shows zoomed area | | placement | "right" \| "left" \| "top" \| "bottom" | "right" | Initial placement of the preview/magnifier popup | | width | number | - | Width of the main image (in pixels) | | height | number | - | Height of the main image (in pixels) | | previewWidth | number | 400 | Width of the preview/magnifier popup (in pixels) | | previewHeight | number | 400 | Height of the preview/magnifier popup (in pixels) | | zoomLevel | number | 1 | Zoom level for magnifier mode (1 = no zoom, 2 = 2x zoom, etc.) | | positionOffset | [number, number] | - | Custom offset for popup position [x, y] | | className | string | - | CSS class name for the container | | classNames | Record<ContainerLayers, string> | - | CSS class names for specific layers (see below) | | style | React.CSSProperties | - | Inline styles for the container | | styles | Record<ContainerLayers, React.CSSProperties> | - | Inline styles for specific layers (see below) |

Container Layers

The classNames and styles props accept an object with the following keys:

• container: The main wrapper div
• img: The main image element
• previewContainer: The popup container (preview/magnifier)
• previewImage: The image inside the popup

Examples

Preview Mode

Shows a full preview of the image when hovering:

<HoverImageMagnifier
  src="/image.jpg"
  alt="Product image"
  mode="preview"
  previewWidth={500}
  previewHeight={500}
  placement="right"
/>

Magnifier Mode

Shows a zoomed-in view that follows your mouse cursor:

<HoverImageMagnifier
  src="/image.jpg"
  alt="Product image"
  mode="magnifier"
  zoomLevel={2.5}
  previewWidth={300}
  previewHeight={300}
  placement="right"
/>

Custom Styling

<HoverImageMagnifier
  src="/image.jpg"
  alt="Product image"
  className="my-custom-container"
  classNames={{
    img: "my-image-class",
    previewContainer: "my-preview-class",
    previewImage: "my-preview-image-class",
  }}
  styles={{
    container: { border: "1px solid #ccc" },
    img: { borderRadius: "8px" },
  }}
/>

Different Placements

// Top placement
<HoverImageMagnifier
  src="/image.jpg"
  placement="top"
/>

// Left placement
<HoverImageMagnifier
  src="/image.jpg"
  placement="left"
/>

// Bottom placement
<HoverImageMagnifier
  src="/image.jpg"
  placement="bottom"
/>

TypeScript Support

This package is written in TypeScript and includes type definitions. All types are exported for your convenience:

import type {
  IHoverImageMagnifier,
  PlacementType,
  BoundaryType,
} from "hover-image-magnifier";

Development Status

This package is currently in active development. The API may change in future versions. We recommend pinning the version in your package.json:

{
  "dependencies": {
    "hover-image-magnifier": "0.1.0"
  }
}

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Repository

GitHub Repository