react-img-mapper

A React Component for Creating Interactive and Highlighted Zones on Images

Key Features

1. Actively Maintained — continuously updated for better performance and compatibility.
2. Built with TypeScript — ensuring type safety and enhanced developer experience.
3. Next.js Ready — fully compatible with SSR and Next.js projects.
4. Lightweight — optimized for minimal bundle size.
5. Well-Documented — detailed examples and API references.
6. Toggle & Reset Support — manage single or multiple highlighted areas with ease.
7. Powerful Callbacks — access image metadata (width, height, etc.) via onLoad.
8. Responsive by Design — adapt seamlessly to various screen sizes and containers.

Installation

Install using your preferred package manager:

# npm
npm install react-img-mapper

# yarn
yarn add react-img-mapper

# pnpm
pnpm install react-img-mapper

Demo & Examples

Live Demo: react-img-mapper.nishargshah.dev

To explore the example locally:

1. Clone the repository:

   git clone https://github.com/img-mapper/img-mapper.git

2. Install dependencies

   pnpm install

3. Start the playground

   pnpm dev:react

4. Open http://localhost:3000 in your browser.

To build the package, run:

pnpm build

Usage Example

Integrate react-img-mapper into your React app easily:

import React from 'react';
import ImageMapper from 'react-img-mapper';

const Mapper = () => {
  const url = 'https://react-img-mapper.nishargshah.dev/assets/example.jpg';
  const name = 'my-map';
  // Example JSON data for mapping areas
  const areas = 'https://react-img-mapper.nishargshah.dev/assets/areas.json';

  return <ImageMapper src={url} name={name} areas={areas} />;
};

export default Mapper;

Properties

| Prop | Type | Description | Default | | ---------------- | -------------------------- | ----------------------------------------------------------------- | -------------------------- | | src | string | URL of the image to display | required | | name | string | The name of the map, used to associate it with the image. | required | | areas | array | Array of area objects, please check Area Properties below | required | | areaKeyName | string | Key name used to uniquely identify areas | id | | isMulti | bool | Allows multiple areas to be highlighted | true | | toggle | bool | Enables toggling highlights for selected areas | false | | active | bool | Enables area listeners and highlighting | true | | disabled | bool | Disable highlighting, listeners, and removes area tag | false | | fillColor | string | Fill color of highlighted zones | rgba(255, 255, 255, 0.5) | | strokeColor | string | Border color of highlighted zones | rgba(0, 0, 0, 0.5) | | lineWidth | number | Border thickness of highlighted zones | 1 | | imgWidth | number | Original width of the image | 0 | | width | number | func => number | Image width (can use a function for dynamic sizing) | 0 | | height | number | func => number | Image height (can use a function for dynamic sizing) | 0 | | natural | bool | Use original dimensions for canvas and wrapper | false | | responsive | bool | Enable responsiveness (requires parentWidth) | false | | parentWidth | number | Maximum width of the parent container for responsiveness | 0 | | containerProps | object | Props for the container <div> element | null | | imgProps | object | Props for the <img> element | null | | canvasProps | object | Props for the <canvas> element | null | | mapProps | object | Props for the <map> element | null | | areaProps | object | array | Props for the <area> elements | null |

Callbacks

| Callback | Triggered On | Signature | | ------------------ | ----------------------------------- | ------------------------------- | | onChange | Clicking an area | (selectedArea, areas) => void | | onImageClick | Clicking outside of mapped zones | (event) => void | | onImageMouseMove | Moving the mouse over the image | (event) => void | | onClick | Clicking a mapped zone | (area, index, event) => void | | onMouseDown | Mouse down on a mapped zone | (area, index, event) => void | | onMouseUp | Mouse up on a mapped zone | (area, index, event) => void | | onTouchStart | Touching a mapped zone | (area, index, event) => void | | onTouchEnd | Ending a touch on a mapped zone | (area, index, event) => void | | onMouseMove | Moving the mouse over a mapped zone | (area, index, event) => void | | onMouseEnter | Hovering over a mapped zone | (area, index, event) => void | | onMouseLeave | Leaving a mapped zone | (area, index, event) => void | | onLoad | Image loaded and canvas initialized | (event, dimensions) => void |

Methods

| Method | Description | | ---------- | ------------------------------------------------------------ | | getRefs | Retrieves refs for the container, canvas, and image elements |

Areas Properties

| Property | Type | Description | Default | | -------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- | | id | string | A unique identifier for the area. If not provided, an index from the array is used. This can be customized using the areaKeyName property. | based on areaKeyName | | shape | string | Specifies the shape of the area: rect, circle, or poly. | required | | coords | array of number | Coordinates defining the area based on its shape: rect: top-left-X, top-left-Y, bottom-right-X, bottom-right-Ycircle: center-X, center-Y, radiuspoly: List of points defining the polygon as point-X, point-Y, ... | required | | active | bool | Enables or disables event listeners and highlighting for the area. | true | | disabled | bool | Disables all interactions, highlighting, and tag additions/removals for the area. | false | | href | string | A target link for clicks on the area. If an onClick handler is provided, the href will not be triggered. | undefined | | fillColor | string | Fill color of the highlighted zone | rgba(255, 255, 255, 0.5) | | strokeColor | string | Border color of the highlighted zone | rgba(0, 0, 0, 0.5) | | lineWidth | number | Border thickness of the highlighted zone | 1 | | preFillColor | string | Pre filled color of the highlighted zone | undefined |

When triggered by an event handler, an area object includes the following additional properties:

| Property | Type | Description | | -------------- | ----------------- | ------------------------------------------------------------------------ | | scaledCoords | array of number | Scaled coordinates adjusted based on the image's dimensions. | | center | array of number | The center or centroid coordinates of the area, represented as [X, Y]. |