react-image-spots

Interactive image hotspots for React. Define spots in code, render anything, navigate between scenes with animations.

Live demo →

Install

npm install react-image-spots

Requires React 17+. No runtime dependencies.

Collecting Spot Positions

Switch to mode="edit" during development. Click anywhere on the image — the x/y position is instantly copied to your clipboard.

<ImageSpotMap
	mode='edit'
	src='/my-photo.jpg'
	onSpotPlace={(pos, index) => console.log(pos)}
	// pos = { x: 32.5, y: 41.2 }
/>

Image Spot Map

Positions are in % so they scale responsively. On hover, other spots fade out automatically.

import { ImageSpotMap } from 'react-image-spots'
import type { SpotDef } from 'react-image-spots'

const spots: SpotDef[] = [
  {
    id: 'kitchen',
    position: { x: 32.5, y: 41.2 },
    size: { w: 5, h: 5 },
    render: ({ isHovered, onMouseEnter, onMouseLeave, onClick }) => (
      <div
        onMouseEnter={onMouseEnter}
        onMouseLeave={onMouseLeave}
        onClick={onClick}
        style={{
          width: '100%',
          height: '100%',
          borderRadius: '50%',
          background: isHovered ? '#3b82f6' : 'white',
          border: '2px solid #3b82f6',
        }}
      />
    ),
  },
]

<ImageSpotMap src="/floor-plan.jpg" spots={spots} />

Image Swap

Add hoverSrc or activeSrc to swap the main image on hover or click.

{
  id: 'room',
  position: { x: 40, y: 50 },
  hoverSrc: '/room-hover.jpg',
  activeSrc: '/room-click.jpg',
  render: (props) => <MySpot {...props} />,
}

Swap Animations

10 built-in presets or custom CSS keyframes. Set globally or per-spot — per-spot overrides global.

// Global
<ImageSpotMap src="/map.jpg" spots={spots} swapAnimation="zoom" />

// Per-spot override
{
  id: 'bridge',
  hoverSrc: '/bridge.jpg',
  swapAnimation: 'glitch',
  render: (props) => <MySpot {...props} />,
}

// Custom keyframes
<ImageSpotMap
  src="/map.jpg"
  spots={spots}
  swapAnimation={{
    enter: "my-anim 400ms ease forwards",
    leave: "my-exit 400ms ease forwards",
    duration: 400,
  }}
/>

Available presets: fade blur zoom zoom-out slide-up slide-down slide-left slide-right flip glitch none

Scene Chain

Navigate between multiple images with smooth transitions.

import { SceneChain } from 'react-image-spots'
import type { SceneDef } from 'react-image-spots'

const scenes: Record<string, SceneDef> = {
  world: {
    src: '/world-map.jpg',
    spots: [
      {
        id: 'castle',
        position: { x: 45, y: 35 },
        size: { w: 6, h: 6 },
        render: ({ onMouseEnter, onMouseLeave, onClick, goTo }) => (
          <button
            onMouseEnter={onMouseEnter}
            onMouseLeave={onMouseLeave}
            onClick={(e) => { onClick(e); goTo('castle') }}
            style={{ width: '100%', height: '100%', borderRadius: '50%' }}
          />
        ),
      },
    ],
  },
  castle: { src: '/castle.jpg', spots: [] },
}

<SceneChain
  scenes={scenes}
  initialScene="world"
  transition="fade"
  showBreadcrumb={false}
  renderBackButton={({ goBack }) => (
    <button onClick={goBack} style={{ position: 'absolute', top: 16, left: 16 }}>
      Back
    </button>
  )}
/>

API

ImageSpotMap

| Prop | Type | Default | Description | | ------------------- | -------------------------------------------- | ----------- | --------------------------------------- | | src | string | required | Image URL | | mode | 'preview' \| 'edit' | 'preview' | Interactive spots or position collector | | spots | SpotDef[] | [] | Spot definitions | | onSpotPlace | (pos, index) => void | — | edit mode: fired on click | | enableImageSwap | boolean | true | Enable image swap on hover/click | | swapDuration | number | 400 | Swap duration ms | | swapAnimation | SwapAnimationPreset \| SwapAnimationCustom | 'fade' | Global swap animation | | hideOthersOnHover | boolean | true | Fade out other spots on hover | | hideHoveredSpot | boolean | false | Also hide the hovered spot | | onSpotHover | (spot) => void | — | Fired on mouse enter | | onSpotClick | (spot) => void | — | Fired on click | | onSpotLeave | (spot) => void | — | Fired on mouse leave |

SceneChain

| Prop | Type | Default | Description | | -------------------- | ----------------------------------------------- | ---------- | ----------------------------- | | scenes | Record<string, SceneDef> | required | Map of sceneId → scene | | initialScene | string | required | Starting scene ID | | transition | 'fade' \| 'none' | 'fade' | Scene transition | | transitionDuration | number | 350 | Duration ms | | swapAnimation | SwapAnimationPreset \| SwapAnimationCustom | 'fade' | Spot swap animation | | hideOthersOnHover | boolean | false | Fade out other spots on hover | | renderBackButton | ({ goBack, canGoBack, history }) => ReactNode | — | Custom back button | | showBackButton | boolean | true | Show built-in back button | | backButtonLabel | string | '← Back' | Built-in back button label | | showBreadcrumb | boolean | true | Show scene breadcrumb | | onSceneChange | (id, scene) => void | — | Fired on scene change | | onSpotClick | (spot, sceneId) => void | — | Fired when spot is clicked |

SpotDef

| Prop | Type | Default | Description | | --------------- | -------------------------------------------- | ---------------- | --------------------------- | | id | string | required | Unique identifier | | position | { x: number, y: number } | required | Position in % (0–100) | | size | { w: number, h: number } | { w: 5, h: 5 } | Hitbox size in % | | render | (props: SpotRenderProps) => ReactNode | required | Your render function | | hoverSrc | string | — | Image URL to swap on hover | | activeSrc | string | — | Image URL to swap on click | | swapAnimation | SwapAnimationPreset \| SwapAnimationCustom | — | Per-spot animation override |

SpotRenderProps

interface SpotRenderProps {
	isHovered: boolean;
	isActive: boolean;
	onMouseEnter: (e: MouseEvent) => void;
	onMouseLeave: (e: MouseEvent) => void;
	onClick: (e: MouseEvent) => void;
	goTo: (sceneId: string) => void; // SceneChain only
	goBack: () => void; // SceneChain only
	canGoBack: boolean; // SceneChain only
}

SwapAnimationCustom

interface SwapAnimationCustom {
	enter: string; // e.g. "my-anim 400ms ease forwards"
	leave?: string;
	duration?: number; // Default: 400
}

License

MIT