Usage

Simple API

Use the default ImagePinner export when you want an image, overlay, and pins in one component.

import { useState } from "react";
import { ImagePinner, type Pin } from "react-image-pinner";

export function ProductImage() {
  const [pins, setPins] = useState<Pin[]>([{ top: 32, left: 45 }]);

  return (
    <ImagePinner
      src="/map.jpg"
      alt="Map photo"
      pins={pins}
      onAddPin={(pin) => setPins((prev) => [...prev, pin])}
      imageClassName="map-image"
    />
  );
}

Pins use percentage top and left (0–100) relative to the rendered image content.

Composable API

For custom structure or render props, use the ImagePinner.* namespace:

import { useState } from "react";
import { ImagePinner, type Pin } from "react-image-pinner";

export function MapPins() {
  const [pins, setPins] = useState<Pin[]>([]);

  return (
    <ImagePinner.Root
      pins={pins}
      onAddPin={(pin) => setPins((prev) => [...prev, pin])}
    >
      <ImagePinner.Image src="/map.jpg" alt="Map photo" className="map-image" />
      <ImagePinner.Overlay>
        <ImagePinner.Items
          render={({ itemNumber }) => (
            <ImagePinner.DefaultPinner itemNumber={itemNumber} />
          )}
        />
      </ImagePinner.Overlay>
    </ImagePinner.Root>
  );
}

ImagePinner.Image accepts an optional render prop for custom image element. Spread the merged props onto your <img>.

Next

See the API reference for every prop and export.