React Img Mapper

React Component to highlight interactive zones in images

1. Promise to be maintained this repository
2. Built in TypeScript
3. Compatible with Next.js
4. Decreased size of bundled
5. Awesome Documentation
6. Selected area will stay highlighted ( Single & Multiple ) with toggle and reset feature
7. Image Reference in Width, Height and onLoad function to access image properties
8. Responsive Image Mapper

Installation

Package: react-img-mapper

# via npm
npm install react-img-mapper --save

# via yarn
yarn add react-img-mapper

Demo & Examples

Live Demo: Demo

To run the example locally

git clone https://github.com/img-mapper/react-docs.git
npm install
npm start

Then open localhost:3000 in a browser.

If you want to change something and want to make a build file, you just need to run npm run build

Usage

Import the component as you normally do, and add it wherever you like in your JSX views as below:

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

const Mapper = props => {
  const URL =
    'https://raw.githubusercontent.com/img-mapper/react-docs/master/src/assets/example.jpg';
  const MAP = {
    name: 'my-map',
    // GET JSON FROM BELOW URL AS AN EXAMPLE AND PUT IT HERE
    areas: 'https://raw.githubusercontent.com/img-mapper/react-docs/master/src/assets/example.json',
  };

  return <ImageMapper src={URL} map={MAP} />;
};

export default Mapper;

Properties

Props	Type	Description	Default
src	string	Image source url	required
map	object	Mapping object	required
areaKeyName	string	unique key name of the json	id
isMulti	bool	Enable/Disable multiple highlight areas by clicking on the specific area	true
toggle	bool	Enable/Disable toggle selected highlighted area	false
active	bool	Enable/Disable listeners and highlighting	true
disabled	bool	Enable/Disable listeners, highlighting and add/remove area tag from the UI	false
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
imgWidth	number	Original image width	0
width	number | func => number	Image width, in function you will get image reference object	0
height	number | func => number	Image height, in function you will get image reference object	0
natural	bool	Give the original dimensions ( height & width ) to canvas and image wrapper	false
responsive	bool	responsive map in all resolution ( for enable it you need to specify parentWidth )	false
parentWidth	number	parent max width for responsive	0

Properties Callback

Props callbacks	Called on	signature
onChange	Area click listener	(selectedArea: MapArea, areas: MapArea[]) => void
onImageClick	Click outside of a zone in image	(event: ImageEvent) => void
onImageMouseMove	Moving mouse on the image itself	(event: ImageEvent) => void
onClick	Click on a zone in image	(area: MapArea, index: number, event: AreaEvent) => void
onMouseDown	Clicks any button of the mouse on a zone in image	(area: MapArea, index: number, event: AreaEvent) => void
onMouseUp	Releases left click of the mouse on a zone in image	(area: MapArea, index: number, event: AreaEvent) => void
onTouchStart	Start to touch the zone in image	(area: MapArea, index: number, event: TouchEvent) => void
onTouchEnd	Releases touch from the zone in image	(area: MapArea, index: number, event: TouchEvent) => void
onMouseMove	Moving mouse on a zone in image	(area: MapArea, index: number, event: AreaEvent) => void
onMouseEnter	Hovering a zone in image	(area: MapArea, index: number, event: AreaEvent) => void
onMouseLeave	Leaving a zone in image	(area: MapArea, index: number, event: AreaEvent) => void
onLoad	Image loading and canvas initialization completed	(event: HTMLImageElement, dimensions: WidthHeight) => void

Methods

Method	Description
getRefs	Get container, canvas and image refs

Map Properties

A map is an object describing highlighted areas in the image.

Its structure is similar to the HTML syntax of mapping:

• map: (object) Object to describe highlighted zones
  • name: (string) Name of the map, used to bind to the image.
  • areas: (array) Array of area objects - area: (object) Shaped like below

Property	Type	Description	Default
id	string	Uniquely identify an area. An index in an array is used if this value is not provided. You can set it with areaKeyName property	based on areaKeyName
shape	string	Either rect, circle or poly	required
coords	array of number	Coordinates delimiting the zone according to the specified shape: rect: top-left-X,top-left-Y,bottom-right-X,bottom-right-Y circle: center-X,center-Y,radius poly: Every point in the polygon path as point-X,point-Y,...	required
active	string	Enable/Disable area listeners and highlighting	true
disabled	string	Enable/Disable area listeners, highlighting and add/remove area tag from the UI	false
href	string	Target link for a click in the zone (note that if you provide an onClick prop, href will be prevented)	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	string	Border thickness of the highlighted zone	1
preFillColor	string	Pre filled color of the highlighted zone	undefined

When received from an event handler, an area is extended with the following properties:

Property	type	Description
scaledCoords	array of number	Scaled coordinates
center	array of number	Coordinates positioning the center or centroid of the area: [X, Y]

License

Distributed with an MIT License. See LICENSE.txt for more details!

Copyright (c) 2024 Nisharg Shah