Skip to content

kholy87/react-img-mapper

 
 

Repository files navigation

React Img Mapper

React Component to highlight interactive zones in images

This repository is based on react-image-mapper but with some enhancements

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

Installation

Package: react-img-mapper

NPM

npm install react-img-mapper --save        

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
    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 string Mapping description { name: generated, areas: [ ] }
containerRef ref help to reset selected highlighted area null
areaKeyName string default unique key name ( required for stayHighlighted ) id
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
width number | func Image width, in function you will get image reference object 0
height number | func Image height, in function you will get image reference object 0
active bool Enable/Disable highlighting true
disabled bool Enable/Disable area listeners and highlighting false
imgWidth number Original image width 0
natural bool Give the original dimensions ( height & width ) to canvas and image wrapper false
stayHighlighted bool You can see the highlighted area after clicking on the particular area false
stayMultiHighlighted bool You can see the multiple highlighted area after clicking on the particular area false
toggleHighlighted bool You can toggle selected highlighted area false
rerenderProps array specify rerenderProps property, if you want to rerender your map with different property []
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
onLoad Image loading and canvas initialization completed (imageRef: obj, parentDimensions: { width, height }): void
onClick Click on a zone in image (area: obj, index: num, event): void
onMouseEnter Hovering a zone in image (area: obj, index: num, event): void
onMouseLeave Leaving a zone in image (area: obj, index: num, event): void
onMouseMove Moving mouse on a zone in image (area: obj, index: num, event): void
onMouseDown Clicks any button of the mouse on a zone in image (area: obj, index: num, event): void
onMouseUp Releases left click of the mouse on a zone in image (area: obj, index: num, event): void
onTouchStart Start to touch the zone in image (area: obj, index: num, event): void
onTouchEnd Releases touch from the zone in image (area: obj, index: num, event): void
onImageClick Click outside of a zone in image (event): void
onImageMouseMove Moving mouse on the image itself (event): void

Methods

Method Description
clearHighlightedArea Clear all selected highlighted area from your map

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 index
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
disabled string Enable/Disable area listeners and highlighting 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) 2021 Nisharg Shah

About

React Component to highlight interactive zones in images

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 100.0%