npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@molecule/app-annotation-pin-react

v4.0.1

Published

Pin/annotation marker overlay with click-to-place pins and label/note popups for 3d-model-viewer, image annotations, map pins, hotspot tours

Readme

@molecule/app-annotation-pin-react

Annotation pin / hotspot overlay primitives.

Exports <AnnotationPin> (single click-to-toggle marker) and <AnnotationLayer> (parent wrapper that manages many pins on a surface). Reusable for 3d-model viewers, image annotations, map pins, and hotspot tours.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { AnnotationLayer, type Pin } from '@molecule/app-annotation-pin-react'

function ImageAnnotator({ src, pins, setPins, activeId, setActiveId }) {
  return (
    <AnnotationLayer
      pins={pins}
      activePinId={activeId}
      onPinClick={(id) => setActiveId(id === activeId ? null : id)}
      onSurfaceClick={({ x, y }) => {
        const id = crypto.randomUUID()
        setPins([...pins, { id, position: { x, y }, label: pins.length + 1 }])
        setActiveId(id)
      }}
    >
      <img src={src} alt="" style={{ width: '100%', display: 'block' }} />
    </AnnotationLayer>
  )
}

Type

feature

Installation

npm install @molecule/app-annotation-pin-react @molecule/app-react @molecule/app-ui react
npm install -D @types/react

API

Interfaces

AnnotationLayerProps

<AnnotationLayer> props.

interface AnnotationLayerProps {
  /** Pins to render on the layer. */
  pins: Pin[]
  /** Optional layer content (the surface to annotate — image, canvas, map tile, etc.). */
  children?: ReactNode
  /**
   * The currently active (popup-open) pin id, or `null` for none. The
   * layer is fully controlled — callers manage selection state.
   */
  activePinId?: string | null
  /** Called with the clicked pin id when a pin marker is clicked. */
  onPinClick?: (pinId: string) => void
  /**
   * Called when the user clicks an empty area of the layer (i.e. not on
   * a pin marker or a popup). Coordinates are in the same space as
   * `Pin.position` — normalised 0..1 by default. Keyboard users get the
   * same action: activating the layer's "add pin" button (Tab to it,
   * then Enter / Space) places a pin at the surface centre.
   */
  onSurfaceClick?: (position: { x: number; y: number }) => void
  /**
   * Whether positions are normalised (0..1) — when `true` the layer
   * computes click coordinates as fractions of its bounding box; when
   * `false` it returns raw pixel offsets. Defaults to `true`.
   */
  normalised?: boolean
  /**
   * Side the popup renders on, relative to its marker. Defaults to `'right'`.
   */
  popupSide?: 'top' | 'bottom' | 'left' | 'right'
  /** Extra classes merged onto the layer root. */
  className?: string
  /** Inline style for the layer root. */
  style?: CSSProperties
}

Pin

A single pin to display on a parent surface. position is in the parent's coordinate space — for image / 2D-canvas overlays this is normalised 0..1 (so the pin re-anchors as the surface resizes); for pixel-positioned overlays callers can pass raw px values and provide their own style overrides via className.

The label/note are pure data — components handle render only. Surfaces supply pin objects via <AnnotationLayer pins={...}> (or render a single pin directly if there is only one).

interface Pin {
  /** Stable identifier (used as React key). */
  id: string
  /** Position in the parent surface's coordinate space (typically normalised 0..1). */
  position: { x: number; y: number }
  /** Short label (e.g. an index or single-word tag) shown inside the pin marker. */
  label?: ReactNode
  /** Longer note / description body, shown inside the popup when the pin is selected. */
  note?: ReactNode
}

AnnotationPinProps

<AnnotationPin> props.

interface AnnotationPinProps {
  /** Position in the parent surface's coordinate space (typically normalised 0..1). */
  position: { x: number; y: number }
  /** Short label (e.g. an index or single-word tag) shown inside the marker. */
  label?: ReactNode
  /** Longer note shown inside the popup when the pin is selected. */
  note?: ReactNode
  /**
   * Whether the pin is currently selected. When `true` the popup is
   * rendered. Selection is controlled — callers manage state in
   * `<AnnotationLayer>` (or themselves) and update via `onClick`.
   */
  selected?: boolean
  /** Click handler — fires when the pin marker is clicked. */
  onClick?: () => void
  /**
   * Side the popup renders on, relative to the marker. Defaults to `'right'`.
   */
  popupSide?: 'top' | 'bottom' | 'left' | 'right'
  /** Extra classes merged onto the root wrapper. */
  className?: string
  /**
   * Whether `position` is normalised (0..1) — when `true` the wrapper
   * positions itself with `%` units so pins re-anchor on resize. When
   * `false` the wrapper uses raw `px` values. Defaults to `true`.
   */
  normalised?: boolean
}

Functions

AnnotationLayer(props)

Wrapper that manages multiple pins on a parent surface. Renders its children (the surface — typically an <img>, <canvas>, or map-tile element) and overlays each pins[] entry as a clickable <AnnotationPin> marker.

Click behaviour:

  • clicking a pin marker fires onPinClick(pinId)
  • clicking empty space on the layer fires onSurfaceClick({ x, y }), which callers typically use to add a new pin. That action lives on an invisible "add annotation pin" button covering the surface (the layer region itself is not interactive — it contains the pin buttons and popups): pointer clicks place a pin at the click position; activating the button with a keyboard (Tab to it, then Enter / Space) or assistive tech places a pin at the surface centre.

The layer itself sets position: relative so absolute pin positioning works without the caller having to provide a wrapper.

All styling routes through getClassMap() (no Tailwind / raw class names). All user-visible text routes through t() so the layer translates via the companion @molecule/app-locales-annotation-pin locale bond.

function AnnotationLayer(props: AnnotationLayerProps): JSX.Element
  • props — Component props.

Returns: The annotation-layer element.

AnnotationPin(props)

A single pin marker (small circle with optional label) rendered at an absolute position on its parent. Clicking the marker toggles its popup (which shows the note body) via the onClick handler.

Positioning is absolute relative to the nearest positioned ancestor — callers must wrap the surface (image, canvas, map) in a position: relative element. <AnnotationLayer> provides this wrapper automatically.

All styling routes through getClassMap() (no Tailwind / raw class names). All user-visible text (aria-labels, fallback note text) routes through t() so the marker translates via the companion @molecule/app-locales-annotation-pin locale bond.

function AnnotationPin(props: AnnotationPinProps): JSX.Element
  • props — Component props.

Returns: The pin element.

Injection Notes

Requirements

Peer dependencies:

  • @molecule/app-react ^4.0.0
  • @molecule/app-ui ^1.0.1
  • react ^18.0.0 || ^19.0.0

Runtime Dependencies

  • @molecule/app-react
  • @molecule/app-ui
  • react

Selection is fully controlled — the layer never stores the active pin; manage activePinId yourself and toggle it in onPinClick. position is normalised 0..1 by default (fractions of the layer box, so pins re-anchor on resize); pass normalised={false} for raw pixel offsets — on BOTH <AnnotationLayer> and any directly-rendered <AnnotationPin>, or clicks and markers will disagree. The layer wraps children in a position: relative box; a bare <AnnotationPin> needs its own positioned ancestor. Translations come from the companion @molecule/app-locales-annotation-pin locale bond.

Translations

Translation strings are provided by @molecule/app-locales-annotation-pin.