Skip to content

Latest commit

 

History

History
145 lines (111 loc) · 11.6 KB

README.md

File metadata and controls

145 lines (111 loc) · 11.6 KB
Raw

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