React-img-mapper NPM

React Img Mapper

React Component to Highlight Interactive Zones in Images

Key Features:

Actively maintained repository.
Built with TypeScript.
Fully compatible with Next.js.
Optimized for smaller bundle size.
Comprehensive documentation.
Toggle and reset functionality for single and multiple highlighted areas.
Access image properties (width, height, etc.) using the onLoad callback.
Fully responsive image mapper.

Installation

Install the package via 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: View Demo

To run the example locally:

Clone the repository:

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

Install dependencies and start the dev server:
```
pnpm playground:install
pnpm playground:dev
```
Open localhost:3000 in your browser.

To build the project, run:

pnpm build

Usage

Here’s how to integrate react-img-mapper into your project:

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

const Mapper = () => {
  const url =
    'https://raw.githubusercontent.com/img-mapper/react-img-mapper/refs/heads/master/resources/example.jpg';
  const name = 'my-map';
  // GET JSON FROM BELOW URL AS AN EXAMPLE AND PUT IT HERE
  const areas =
    'https://raw.githubusercontent.com/img-mapper/react-img-mapper/refs/heads/master/resources/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	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]`.