# react-img-mapper > A React Component for Creating Interactive and Highlighted Zones on Images Latest version **2.0.2** (published 2025-10-18) · MIT license · 0 weekly downloads ## Install ```sh npm install react-img-mapper pnpm add react-img-mapper yarn add react-img-mapper bun add react-img-mapper ``` ## Health **Score 55/100 (C)** — status: stable. Positive: has types; esm support; no vulnerabilities. Warnings: low downloads. ## Facts | | | |---|---| | Version | 2.0.2 | | Published | 2025-10-18 | | First published | 2021-01-01 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >=16.0.0 | | Dependencies | 1 | | Unpacked size | 38.3 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 155 | | Author | Nisharg Shah | | Maintainers | nishargshah | | Keywords | react, react-img-mapper, react-image-mapper, img-mapper, image-mapper, img mapper, image mapper, docs react img mapper, react img mapper docs, docs react image mapper, react image mapper docs | ## Links - npm: https://www.npmjs.com/package/react-img-mapper - Repository: https://github.com/img-mapper/img-mapper - Homepage: https://react-img-mapper.nishargshah.dev - Issues: https://github.com/img-mapper/img-mapper/issues - npm.io page: https://npm.io/package/react-img-mapper ## Dependencies (1) - [react-fast-compare](https://npm.io/package/react-fast-compare.md) ^3.2.2 ## Alternatives - [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads - [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads - [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads - [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads - [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads ## Recent versions - 2.0.2 (latest) — 2025-10-18 - 2.0.0-alpha.9 (alpha) — 2025-01-26 - 2.0.1 — 2025-10-18 - 2.0.0 — 2025-01-26 - 2.0.0-alpha.6 — 2025-01-25 - 2.0.0-alpha.5 — 2025-01-14 - 2.0.0-alpha.4 — 2025-01-14 - 2.0.0-alpha.3 — 2023-12-24 - 2.0.0-alpha.2 — 2023-12-24 - 2.0.0-alpha.1 — 2023-12-24 - 2.0.0-alpha.0 — 2023-12-24 - 1.5.1 — 2023-04-02 - 1.5.0 — 2023-02-13 - 1.4.3 — 2023-02-13 - 1.4.2 — 2023-02-12 - … 44 more at https://npm.io/package/react-img-mapper/versions ## README # `react-img-mapper` [![NPM Version](https://img.shields.io/npm/v/react-img-mapper)](https://www.npmjs.com/package/react-img-mapper) [![NPM Downloads](https://img.shields.io/npm/dw/react-img-mapper)](https://www.npmjs.com/package/react-img-mapper) [![NPM Last Update](https://img.shields.io/npm/last-update/react-img-mapper)](https://www.npmjs.com/package/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: ```bash # 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](https://react-img-mapper.nishargshah.dev) To explore the example locally: 1. **Clone the repository:** ```bash git clone https://github.com/img-mapper/img-mapper.git ``` 2. **Install dependencies** ```bash pnpm install ``` 3. **Start the playground** ```bash pnpm dev:react ``` 4. Open [`http://localhost:3000`](http://localhost:3000) in your browser. To build the package, run: ```bash pnpm build ``` --- ## Usage Example Integrate `react-img-mapper` into your React app easily: ```javascript 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 ; }; 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 `
` element | `null` | | `imgProps` | _object_ | Props for the `` element | `null` | | `canvasProps` | _object_ | Props for the `` element | `null` | | `mapProps` | _object_ | Props for the `` element | `null` | | `areaProps` | _object_ \| _array_ | Props for the `` 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]`. | --- _Source: https://npm.io/package/react-img-mapper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._