@rockshin/react-image-annotation NPM

React Image annotation project based on tldraw

An image annotation tool for ai project that manual annotation for images, easy to use!

Big Thanks to tldraw !

install

npm

npm install @rockshin/react-image-annotation tldraw

pnpm

pnpm add @rockshin/react-image-annotation tldraw

Easy to use:

Don't forget import styles import 'tldraw/tldraw.css';

Basic Usage

import { ImageAnnotationEditor } from '@rockshin/react-image-annotation'
import 'tldraw/tldraw.css'

function App() {
  const images = [
    {
      id: '1',
      src: 'https://example.com/image1.jpg',
      annotations: [], // Initial annotations (optional)
    },
  ]

  const handleDone = ({ annotations, image }) => {
    console.log('Annotations:', annotations)
    console.log('Image:', image)
  }

  return (
    <div style={{ width: '100%', height: '600px', position: 'relative' }}>
      <ImageAnnotationEditor
        images={images}
        onDone={handleDone}
        tools={{
          eraser: { enabled: true },
          text: { enabled: true },
        }}
      />
    </div>
  )
}

Advanced Usage

Multiple Images with Initial Annotations

import { ImageAnnotationEditor } from '@rockshin/react-image-annotation'

function AdvancedExample() {
  const images = [
    {
      id: '1',
      src: 'https://example.com/image1.jpg',
      annotations: [
        {
          id: 'anno1',
          x: 100,
          y: 100,
          width: 200,
          height: 150,
          rotation: 0,
          label: '1',
          timestamp: Date.now(),
          metadata: {
            color: 'red',
            createdBy: 'user1',
            modifiedAt: Date.now(),
            version: 1,
            tags: [],
            isVerified: false,
          },
        },
      ],
    },
    {
      id: '2',
      src: 'https://example.com/image2.jpg',
      annotations: [],
    },
  ]

  return (
    <div style={{ width: '100%', height: '800px', position: 'relative' }}>
      <ImageAnnotationEditor
        images={images}
        initialImageIndex={0}
        tools={{
          eraser: { enabled: true },
          text: { enabled: true },
        }}
        outputTriggerOn={{
          created: true, // Trigger onDone when annotation is created
          changed: true, // Trigger onDone when annotation is modified
          deleted: true, // Trigger onDone when annotation is deleted
          navigated: false, // Trigger onDone when image is navigated
        }}
        onAnnotationCreated={({ image, annotation }) => {
          console.log('New annotation:', annotation)
        }}
        onAnnotationChange={({ image, annotation }) => {
          console.log('Modified annotation:', annotation)
        }}
        onAnnotationDeleted={({ image, annotation }) => {
          console.log('Deleted annotation:', annotation)
        }}
        onImageChange={({ index, image }) => {
          console.log('Current image:', index, image)
        }}
        onImageLoadError={error => {
          console.error('Image load error:', error)
        }}
        onDone={({ annotations, image }) => {
          console.log('Final annotations:', annotations)
        }}
      />
    </div>
  )
}

Features

🎯 Auto-incrementing numbered annotations (1-999)
🖼️ Multi-image support with navigation
🔄 Automatic reuse of deleted annotation numbers
🎨 Customizable toolbar with:
- Rectangle tool
- Text tool (optional)
- Eraser tool (optional)
- Hand tool for navigation
📊 Comprehensive event callbacks
🖼️ Support for both URL and base64 image sources
🔄 Automatic image fitting with aspect ratio preservation
⚡ Real-time annotation updates
🔒 Locked base image to prevent accidental movement

Important Notes

Container Requirements:
- Parent container must have position: relative
- Explicit dimensions (width/height) are required
Image Handling:
- Images automatically fit to viewport
- Original aspect ratio is maintained
- Base image is locked to prevent accidental movement
Annotation Limits:
- Supports up to 999 numbered annotations per image
- Numbers are automatically reused when annotations are deleted
Error Handling:
- Built-in error handling for image loading
- Retry mechanism for failed image loads
- Navigation options during error states