React Image Marker Viewer 0.1.6

A powerful, zero-config, and responsive image annotation library for React. Add markers to images, edit details, upload photos, and manage state with ease.

Features

• ⚡ Zero Config: No external CSS import required! Styles are automatically injected.
• 🎯 Responsive & Adaptive: Images automatically fit within your container (vertically or horizontally) while maintaining aspect ratio. Markers stay in correct percentage-based positions.
• 🛠️ Full Control: Logic is separated into a useMarkerState hook, giving you full control over the marker data.
• 🖼️ Image Support: Works with any image URL or base64 string.
• 📝 Rich Details: Add titles, notes, and colors to markers.
• 📸 Photo Attachments: Upload up to 3 photos per marker (stored as Base64).
• 🔍 Lightbox: Built-in full-screen lightbox with zoom and pan support.
• 🖱️ Drag & Drop: Drag markers to reposition them.
• 🗑️ Long Press Delete: Hold a marker for 500ms to delete it.
• 🌍 Localization: Auto-detects English (en), Turkish (tr), and Spanish (es).
• 🎨 Scoped Styling: Uses semantic class names (e.g., .react-image-marker-container) for easy override.

Installation

npm install react-image-marker-viewer
# or
yarn add react-image-marker-viewer

Usage

1. Import Hook and Component

import { ImageMarker, useMarkerState } from 'react-image-marker-viewer';

function App() {
  // 1. Initialize state with the hook
  const { 
    markers,       // Read: Current array of markers
    addMarker,     // Write: Function to add a marker
    updateMarker,  // Write: Function to update a marker
    removeMarker,  // Write: Function to delete a marker
    setAllMarkers  // Write: Function to replace all markers (e.g. from DB)
  } = useMarkerState();

  return (
    // 2. Define a container with your desired dimensions
    <div style={{ width: '100%', height: '600px', border: '1px solid #ccc' }}>
      
      {/* 3. Render the component */}
      <ImageMarker
        src="https://example.com/image.jpg"
        markers={markers}
        onAddMarker={addMarker}
        onUpdateMarker={updateMarker}
        onDeleteMarker={removeMarker}
      />
      
    </div>
  );
}

2. Read-Only Mode

You can render the component in read-only mode, which disables adding, moving, or editing markers. Clicking a marker (if needed) can still trigger custom logic or be ignored.

<ImageMarker
  src="..."
  markers={markers}
  readOnly={true} // Markers are visible but not interactive
/>

Props: ImageMarker

| Prop | Type | Description | |------|------|-------------| | src | string | URL or Base64 string of the image. | | markers | Marker[] | Array of marker objects. | | onAddMarker | (marker: Marker) => void | Callback when a new marker is saved. | | onUpdateMarker | (id: string, updates: Partial<Marker>) => void | Callback when a marker is updated. | | onDeleteMarker | (id: string) => void | Callback when a marker is deleted. | | readOnly | boolean | Optional. If true, disables adding, editing, or moving markers. Default: false. |

Hook: useMarkerState

A helper hook to manage marker state easily. You can essentially build your own UI around the data returned by this hook.

const { 
  markers,        // Marker[]
  addMarker,      // (marker: Marker) => void
  updateMarker,   // (id: string, updates: Partial<Marker>) => void
  removeMarker,   // (id: string) => void
  setAllMarkers   // (markers: Marker[]) => void
} = useMarkerState();

Styling & Class Names

The library injects its own CSS automatically. You can override styles by targeting these semantic class names:

| Class Name | Description | |------------|-------------| | .react-image-marker-container | The outer container. | | .react-image-marker-wrapper | The wrapper around the image (positioning context). | | .react-image-marker-image | The actual image element. | | .react-image-marker-item | The circular marker element. | | .react-image-marker-popup-content | The editing popup container. | | .react-image-marker-btn-save | The "Save" button. |

License

MIT