react-img-mapper

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-Y circle: center-X, center-Y, radius poly: 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].