react-img-cutout

react-img-cutout provides a simple, composable component for creating interactive image regions. It enables pixel-perfect interaction using transparent PNG cutouts, while also supporting standard bounding boxes and polygons for geometric shapes.

Quick Start

1) Install

npm install react-img-cutout

Peer dependencies:

• react >= 18
• react-dom >= 18

2) Render a viewer

import { CutoutViewer } from "react-img-cutout"

export function ProductHero() {
  return (
    <CutoutViewer
      mainImage="/images/main.png"
      mainImageAlt="Product scene"
      effect="elevate"
      onSelect={(id) => console.log("selected:", id)}
    >
      <CutoutViewer.Cutout
        id="shoe"
        src="/images/cutouts/shoe.png"
        label="Shoe"
      >
        <CutoutViewer.Overlay placement="top-center">
          <button>View details</button>
        </CutoutViewer.Overlay>
      </CutoutViewer.Cutout>

      <CutoutViewer.Cutout
        id="bag"
        src="/images/cutouts/bag.png"
        label="Bag"
      />

      {/* No image needed — define regions with coordinates */}
      <CutoutViewer.BBoxCutout
        id="logo"
        bounds={{ x: 0.05, y: 0.05, w: 0.15, h: 0.1 }}
        label="Logo"
      />

      <CutoutViewer.PolygonCutout
        id="accent"
        points={[[0.7, 0.2], [0.9, 0.2], [0.85, 0.5], [0.65, 0.45]]}
        label="Accent"
      />
    </CutoutViewer>
  )
}

Cutout Types

The library supports three different cutout types, each suited for different use cases.

Image Cutout (CutoutViewer.Cutout)

The original cutout type — uses a transparent PNG aligned to the same coordinate space as the main image. Hit-testing is performed per-pixel using the alpha channel.

<CutoutViewer.Cutout
  id="shoe"
  src="/images/cutouts/shoe.png"
  label="Shoe"
>
  <CutoutViewer.Overlay placement="top-center">
    <button>View details</button>
  </CutoutViewer.Overlay>
</CutoutViewer.Cutout>

| Prop | Type | Description | |------|------|-------------| | id | string | Unique identifier for the cutout | | src | string | URL of the cutout image (transparent PNG, same resolution as mainImage) | | label | string? | Human-readable label (used as alt text) | | effect | HoverEffectPreset \| HoverEffect? | Override the viewer-level hover effect for this cutout | | renderLayer | (props: RenderLayerProps) => ReactNode? | Custom renderer replacing the default <img> | | children | ReactNode? | Overlay content |

Bounding Box Cutout (CutoutViewer.BBoxCutout)

Defines a rectangular region using normalized 0–1 coordinates. No image required — the component renders a styled rectangle. Ideal for highlighting areas of the image programmatically (e.g. from object-detection output).

<CutoutViewer.BBoxCutout
  id="face"
  bounds={{ x: 0.3, y: 0.1, w: 0.2, h: 0.25 }}
  label="Face"
>
  <CutoutViewer.Overlay placement="top-center">
    <span>Detected face</span>
  </CutoutViewer.Overlay>
</CutoutViewer.BBoxCutout>

| Prop | Type | Description | |------|------|-------------| | id | string | Unique identifier for the cutout | | bounds | { x, y, w, h } | Normalized 0–1 bounding box (x and y are the top-left corner) | | label | string? | Human-readable label | | effect | HoverEffectPreset \| HoverEffect? | Override the viewer-level hover effect for this cutout | | renderLayer | (props: RenderLayerProps) => ReactNode? | Custom renderer replacing the default rectangle | | children | ReactNode? | Overlay content |

Polygon Cutout (CutoutViewer.PolygonCutout)

Defines an arbitrary closed shape using an array of [x, y] normalized 0–1 points. Rendered as an SVG <polygon>. Great for non-rectangular regions such as segmentation masks or hand-drawn annotations.

<CutoutViewer.PolygonCutout
  id="lake"
  points={[
    [0.2, 0.6],
    [0.5, 0.55],
    [0.6, 0.7],
    [0.35, 0.8],
  ]}
  label="Lake"
>
  <CutoutViewer.Overlay placement="center">
    <span>Lake area</span>
  </CutoutViewer.Overlay>
</CutoutViewer.PolygonCutout>

| Prop | Type | Description | |------|------|-------------| | id | string | Unique identifier for the cutout | | points | [number, number][] | Array of normalized 0–1 [x, y] points forming a closed path | | label | string? | Human-readable label | | effect | HoverEffectPreset \| HoverEffect? | Override the viewer-level hover effect for this cutout | | renderLayer | (props: RenderLayerProps) => ReactNode? | Custom renderer replacing the default SVG polygon | | children | ReactNode? | Overlay content |

Draw Polygon (CutoutViewer.DrawPolygon)

Adds an interactive drawing layer over the viewer so users can define their own polygon regions directly on the image. Completed polygons are returned via onComplete as normalized [x, y][] coordinates, ready for direct use with PolygonCutout.

const [regions, setRegions] = useState<[number, number][][]>([])
const [drawing, setDrawing] = useState(true)

<CutoutViewer mainImage="/photo.png">
  <CutoutViewer.DrawPolygon
    enabled={drawing}
    onComplete={(points) => setRegions((prev) => [...prev, points])}
    strokeColor="#3b82f6"
    minPoints={3}
    closeThreshold={0.03}
  />
  {regions.map((pts, i) => (
    <CutoutViewer.PolygonCutout key={i} id={`region-${i}`} points={pts} />
  ))}
</CutoutViewer>

| Interaction | Effect | |---|---| | Click | Add a vertex | | Click near first vertex (≥ minPoints) | Snap-close → fires onComplete | | Double-click | Complete the polygon immediately | | Right-click | Remove the last vertex | | Esc | Cancel and reset the in-progress drawing |

| Prop | Type | Default | Description | |---|---|---|---| | onComplete | (points: [number, number][]) => void | — | Called with normalized points when a polygon is finished | | enabled | boolean | true | Toggle drawing on/off without unmounting. When false, pointer events pass through to the viewer and any in-progress drawing is cleared | | strokeColor | string | "#3b82f6" | Accent color for the in-progress polygon overlay | | minPoints | number | 3 | Minimum vertices required before snap-close or double-click complete | | closeThreshold | number | 0.03 | Normalized (0–1) snap radius for closing near the first vertex | | style | CSSProperties? | — | Additional styles for the overlay container | | className | string? | — | Additional class name for the overlay container |

useDrawPolygon (headless hook)

For building completely custom drawing UIs without the built-in SVG overlay:

import { useDrawPolygon } from "react-img-cutout"

const { points, previewPoint, willClose, reset, containerRef, containerProps } =
  useDrawPolygon({
    onComplete: (pts) => console.log(pts),
    minPoints: 3,
    closeThreshold: 0.03,
  })

return (
  <div ref={containerRef} style={{ position: "relative" }} {...containerProps}>
    <img src="/main.png" style={{ width: "100%" }} />
    {/* render your own SVG overlay using points / previewPoint / willClose */}
  </div>
)

Public API

• CutoutViewer
  • Props: mainImage, mainImageAlt, effect, enabled, showAll, alphaThreshold, hoverLeaveDelay, onHover, onActiveChange, onSelect
• CutoutViewer.Cutout — image-based cutout (alpha hit-testing)
• CutoutViewer.BBoxCutout — bounding-box cutout (rectangular region)
• CutoutViewer.PolygonCutout — polygon cutout (arbitrary closed shape)
• CutoutViewer.DrawPolygon — interactive polygon drawing overlay
  • Props: onComplete, enabled, strokeColor, minPoints, closeThreshold, style, className
• CutoutViewer.Overlay
  • Props: placement, className, style
• useCutout()
  • Read nearest cutout state (id, bounds, isActive, isHovered, isSelected, effect)
• useDrawPolygon(options)
  • Headless hook; returns points, previewPoint, willClose, reset, containerRef, containerProps
• hoverEffects
  • Built-in presets: elevate, glow, lift, subtle, trace, shimmer
• defineKeyframes(name, css) — helper for declaring CSS @keyframes in custom effects

How It Works

• Image cutouts are loaded into an offscreen canvas; opaque bounds and alpha data are computed once for pixel-level hit-testing.
• BBox cutouts use simple point-in-rect checks against normalized coordinates.
• Polygon cutouts use a ray-casting algorithm for point-in-polygon testing.
• Pointer positions are normalized to the container and hit-tested from front to back.
• Click locks selection; clicking empty space clears selection.
• Overlays are positioned from normalized cutout bounds using one of 9 placements.

Important Implementation Notes

• Use transparent PNG/WebP cutouts aligned to the same coordinate space as mainImage.
• Best results come from matching cutout resolution to the base image resolution.
• BBox and Polygon cutouts do not require any image — they are defined purely by coordinates.
• Geometry cutouts (BBox/Polygon) are invisible when idle and appear on hover/selection, unlike image cutouts which blend naturally with the background.
• If a cutout image cannot be read from canvas (for example, CORS restrictions), hit testing for that cutout gracefully falls back and does not crash.
• The component does not require Tailwind to render correctly.

Effects

Pass a preset name or a fully custom HoverEffect object to the effect prop.

Built-in presets

| Preset | Description | |--------|-------------| | elevate | Lifts the hovered cutout with a blue glow and deep shadow | | glow | Warm glow around the hovered cutout, no lift | | lift | Strong lift with deep shadow, no color glow | | subtle | Minimal — dims non-hovered cutouts with no animation | | trace | A white dash continuously traces the cutout border | | shimmer | style brightness flash that sweeps over the hovered subject |

Custom static effects

import { CutoutViewer, type HoverEffect } from "react-img-cutout"

const customEffect: HoverEffect = {
  name: "neon",
  transition: "all 0.4s ease",
  mainImageHovered: { filter: "brightness(0.2) grayscale(1)" },
  vignetteStyle: { background: "rgba(0,0,0,0.45)" },
  cutoutActive: { transform: "scale(1.03)", opacity: 1 },
  cutoutInactive: { transform: "scale(1)", opacity: 0.35 },
  cutoutIdle: { transform: "scale(1)", opacity: 1 },
}

Custom animated effects

Use defineKeyframes to declare CSS @keyframes that the viewer injects automatically. Reference the keyframe name in any animation property.

import { defineKeyframes, type HoverEffect } from "react-img-cutout"

const pulse = defineKeyframes("my-pulse", `
  0%, 100% { transform: scale(1);    filter: brightness(1);    }
  50%      { transform: scale(1.06); filter: brightness(1.15); }
`)

const pulseEffect: HoverEffect = {
  name: "pulse",
  transition: "all 0.4s ease",
  keyframes: [pulse],
  mainImageHovered: { filter: "brightness(0.3)" },
  vignetteStyle: { background: "rgba(0,0,0,0.4)" },
  cutoutActive: {
    animation: `${pulse.name} 1.2s ease-in-out infinite`,
    opacity: 1,
  },
  cutoutInactive: { opacity: 0.3 },
  cutoutIdle: { opacity: 1 },
}

Geometry cutouts (BBox / Polygon) also support strokeDasharray and animation on their geometryActive style for SVG-level animations like the built-in trace effect.

Local Development

• npm run storybook for interactive component testing
• npm run lint for lint checks
• npm run build:lib to generate dist/ for npm