API reference

Types

Pin

type Pin = {
  top: number;
  left: number;
  id?: string | number;
};

top and left are percentages (0–100) of the visible image content box.

PinnerComponentProps

Used with custom pin components on the composite ImagePinner:

type PinnerComponentProps = {
  top: number;
  left: number;
  itemNumber: number;
};

ImagePinnerImageRenderProps

Props passed to ImagePinner.Image’s render function (spread onto <img />):

type ImagePinnerImageRenderProps = ComponentPropsWithoutRef<"img"> & {
  ref: Ref<HTMLImageElement>;
  "data-react-image-pinner-image"?: "";
};

---

ImagePinner (composite)

A convenience wrapper. Combines Root, Image, Overlay, and `Item.

Prop	Type	Description
src	string	Image URL.
pins	T[] where T extends Pin	Pin list.
onAddPin	(pin: Pin) => void	Called when the user clicks the image to add a pin (optional).
pinnerComponent	ComponentType<PinnerComponentProps & T>	Custom pin UI (optional).
alt	string	Image alt text (default "").
imageClassName	string	Class on the <img> (default "").
containerClassName	string	Class on the outer wrapper.
renderDefaultPinner	(itemNumber: number, pin: T) => ReactElement	Fallback when pinnerComponent is omitted.
renderImage	(props: ImagePinnerImageRenderProps) => ReactElement	Same as ImagePinner.Image render.

---

Composable components

ImagePinner.Root

Context provider and relative wrapper (data-react-image-pinner). Renders a <div> element.

Prop	Type
pins	T[]
onAddPin	(pin: Pin) => void (optional)
children	ReactNode
className	string (optional)
style	CSSProperties (optional)

ImagePinner.Image

Registers the image, handles resize, and click-to-add when onAddPin is set. Renders an <img> element.

Prop	Type
render	(props: ImagePinnerImageRenderProps) => ReactElement (optional)

ImagePinner.Overlay

Absolutely positioned overlay aligned to the image for rendering items. Renders a <div> element.

ImagePinner.Item

Single pin container. Positions children at pin.left% / pin.top% with translate(-50%, -50%). Renders a <div> element.

Prop	Type
pin	Pin

ImagePinner.Items

Maps pins from context. Renders each pin with <ImagePinner.Item>.

Prop	Type
render	({ pin, itemNumber }) => ReactNode
getKey	(pin, itemNumber) => string | number (optional)

ImagePinner.DefaultPinner

Small numbered circle fallback (itemNumber is 0-based). Renders a <span> element.

---

Utilities

getRenderedContentBox(image: HTMLImageElement)

Returns { left, top, width, height } of the image content as drawn. For advanced layout outside the provided overlay.