React Bounding Box Annotator

A lightweight and customizable image bounding box annotation component for React.

👉 Demo: https://bbox-annotator.netlify.app/

👉 NPM: https://www.npmjs.com/package/react-bbox-annotator

⚡ Features

• Simple React component with intuitive props
• Automatically scales the image to its parent container
• Bounding box coordinates remain in reference to the original image size
• Emits annotation updates via a callback
• Supports free-text labels or predefined label lists
• Works in any modern React setup (Vite, Next.js, CRA, etc.)
• Select and move existing boxes (drag to reposition)
• Resize boxes with 8 handles (corners and edges)
• Edit labels on existing boxes (double‑click a box)

📦 Installation

npm install react-bbox-annotator

React version support

This package requires React 18:

npm install react@^18.2.0 react-dom@^18.2.0

📚 Usage Example

import React, { useState } from 'react';
import BBoxAnnotator { type EntryType } from 'react-bbox-annotator';

const App = () => {
  const labels = ['Mama cow', 'Baby cow'];
  const [entries, setEntries] = useState<EntryType[]>([]);

  return (
    <>
      <div style={{ width: '60%' }}>
        <BBoxAnnotator
          url="https://milkgenomics.org/wp-content/uploads/2013/08/bigstock-cows-mother-and-baby-3998546.jpg"
          inputMethod="select"
          labels={labels}
          onChange={(e) => setEntries(e)}
        />
      </div>

      <pre>{JSON.stringify(entries, null, 2)}</pre>
    </>
  );
};

export default App;

or in CommonJS:

const BBoxAnnotator = require('react-bbox-annotator').default;

🖱️ Interactions

• Select a box: click it (selected box shows a blue border)
• Move a box: drag a selected box
• Resize a box: drag any of the 8 handles (corners/edges)
• Edit a label: double‑click a box
• Delete a box: click the close button that appears on hover

❓ Why use this component?

If you're building an image labeling platform, dataset creation tool, or computer vision annotation UI, this component saves you from:

• handling mouse interactions
• scaling images
• aligning coordinates
• mapping UI boxes to original image dimensions
• You get a clean, plug-and-play React component that handles all the messy UI logic.

🔧 Available Props

| Prop | Type | Required | Default | Description | | --------------- | -------------------------------- | -------- | ------- | ----------------------------------------------------------------------------- | | url | string | ✔️ Yes | — | URL of the image to annotate. | | inputMethod | 'text' \| 'select' | ✔️ Yes | — | Annotation input mode. text = free typing, select = choose from labels. | | onChange | (entries: EntryType[]) => void | ✔️ Yes | — | Callback fired whenever annotations are added, moved, resized, edited, or removed. | | labels | string[] | No | [] | List of predefined labels (used only when inputMethod="select"). | | borderWidth | number | No | 2 | Width of the bounding box border (in pixels). |

export interface EntryType {
  left: number;
  top: number;
  width: number;
  height: number;
  label: string;
}

📄 License

MIT © Younes Zadi