React Image Maps

Responsive HTML image maps for React with automatic coordinate scaling

A simple React component for HTML image maps with the key feature that native <map> lacks: automatic responsive coordinate scaling.

Perfect for interactive image maps that need to work at any screen size, in fluid layouts, or on mobile — without any CSS tricks.

Installation

npm install react-image-maps

Quick Start

import React from 'react'
import ReactImageMaps, { Area } from 'react-image-maps'

const areas: Area[] = [
  {
    shape: 'rect',
    coords: [34, 44, 270, 350],
    alt: 'Computer',
    href: 'https://example.com/computer',
  },
  {
    shape: 'circle',
    coords: [337, 300, 44],
    alt: 'Coffee cup',
    onClick: (area) => console.log('clicked', area.alt),
  },
]

function App() {
  return (
    <ReactImageMaps
      src="/office.jpg"
      alt="Office scene"
      mapName="office-map"
      areas={areas}
      originalWidth={800}
    />
  )
}

The originalWidth should match the natural pixel width of the source image (or whatever coordinate space your coords were defined in). The component scales all coordinates proportionally as the image resizes.

API Reference

<ReactImageMaps />

Props

Prop	Type	Required	Description
src	string	Yes	URL of the image to display
alt	string	No	Alt text for the <img> element
mapName	string	Yes	Unique name for the <map> element
areas	Area[]	Yes	Array of clickable area definitions
originalWidth	number	Yes	Pixel width the coordinates were defined at

Area object

Property	Type	Required	Description
shape	'rect' | 'circle' | 'poly'	No	Shape of the area. Defaults to 'rect'
coords	number[]	Yes	Coordinates in original image pixel space, scaled automatically at render time
alt	string	No	Alt text for the area
href	string	No	Link target. Defaults to '#' when onClick is provided
onClick	(area: Area) => void	No	Click handler. Prevents default navigation automatically

TypeScript Support

The component is fully typed and exports the following types:

import ReactImageMaps, { type Area, type ReactImageMapsProps } from 'react-image-maps'

const areas: Area[] = [
  { shape: 'rect', coords: [0, 0, 100, 100], alt: 'Top left region' }
]

Examples

Click Handlers

const areas: Area[] = [
  {
    shape: 'rect',
    coords: [34, 44, 270, 350],
    alt: 'Product A',
    onClick: (area) => {
      console.log('Clicked:', area.alt)
    },
  },
]

Mixed Shapes

const areas: Area[] = [
  // Rectangle: [x1, y1, x2, y2]
  { shape: 'rect', coords: [0, 0, 200, 150], alt: 'Header region' },

  // Circle: [cx, cy, radius]
  { shape: 'circle', coords: [300, 200, 50], alt: 'Logo' },

  // Polygon: [x1, y1, x2, y2, x3, y3, ...]
  { shape: 'poly', coords: [100, 0, 200, 100, 0, 100], alt: 'Triangle' },
]

With Navigation

const areas: Area[] = [
  {
    shape: 'rect',
    coords: [34, 44, 270, 350],
    alt: 'Go to products',
    href: '/products',
  },
]

Why This Component?

• Native <map> limitation: Coordinates are fixed pixel values — they break when the image scales
• This component solves that: Uses ResizeObserver to track rendered width and scales coordinates live
• React-friendly: Manages the observer lifecycle with useEffect
• Simple API: Familiar <area> shape and coord conventions, just pass arrays
• TypeScript: Full type safety out of the box

License

MIT License. See LICENSE for details.