@karlorz/react-image-annotate

React Image Annotate

The best image/video annotation tool ever. Check out the demo here. Or the code sandbox here.

Features

• Simple input/output format
• Bounding Box, Point and Polygon Annotation
• Zooming, Scaling, Panning
• Multiple Images
• Cursor Crosshair
• Headless Architecture (v3.x) - Build custom UIs with useAnnotator hook
• Internationalization (i18n) - Built-in support for EN/ZH/VI languages
• Theme Customization - PingFang font stack with Material-UI v6

Usage

Install with npm (recommended):

npm install @karlorz/react-image-annotate

Or with bun (alternative):

bun add @karlorz/react-image-annotate

import React from "react";
import ReactImageAnnotate from "@karlorz/react-image-annotate";

const App = () => (
  <ReactImageAnnotate
    labelImages
    regionClsList={["Alpha", "Beta", "Charlie", "Delta"]}
    regionTagList={["tag1", "tag2", "tag3"]}
    images={[
      {
        src: "https://placekitten.com/408/287",
        name: "Image 1",
        regions: []
      }
    ]}
  />
);

export default App;

Headless Architecture (v3.x)

For custom UIs, use the headless useAnnotator hook:

import { useAnnotator } from "@karlorz/react-image-annotate/headless";

function MyCustomAnnotator() {
  const { state, actions, regions, currentImage } = useAnnotator({
    images: [{ src: '/image.jpg', name: 'Test' }],
    onExit: (output) => console.log(output)
  });

  return (
    <div>
      <button onClick={() => actions.selectTool('create-box')}>
        Box Tool
      </button>
      <canvas {...actions.getCanvasProps()} />
      {regions.map(r => (
        <div key={r.id}>
          {r.cls}
          <button onClick={() => actions.deleteRegion(r)}>Delete</button>
        </div>
      ))}
    </div>
  );
}

See examples/headless/ for complete examples with Tailwind CSS, Semi Design, and vanilla React.

Internationalization (i18n)

Wrap your app with I18nProvider for multi-language support:

import { I18nProvider } from "@karlorz/react-image-annotate";

<I18nProvider language="zh"> {/* en, zh, or vi */}
  <ReactImageAnnotate {...props} />
</I18nProvider>

Or provide custom translations:

<I18nProvider
  language="fr"
  translations={{
    fr: { 'header.save': 'Enregistrer', ... }
  }}
>
  <ReactImageAnnotate {...props} />
</I18nProvider>

Theme Support (Light/Dark Mode)

The component supports both light and dark themes:

// Simple string mode (recommended)
<ReactImageAnnotate theme="dark" {...props} />
<ReactImageAnnotate theme="light" {...props} />

// Custom Material-UI theme
import { createTheme } from '@mui/material/styles'

const customTheme = createTheme({
  palette: {
    mode: 'dark',
    primary: { main: '#3f51b5' },
    background: {
      default: '#1a1a1a',
      paper: '#2a2a2a',
    },
  },
})

<ReactImageAnnotate theme={customTheme} {...props} />

Theme Integration: The component respects the MUI theme palette and will automatically style all internal components (workspace, sidebars, dialogs) according to the theme mode. Perfect for applications with dynamic theme switching!

To get the proper fonts, make sure to import the Inter UI or Roboto font, the following line added to a css file should suffice.

@import url("https://rsms.me/inter/inter.css");

Props

All of the following properties can be defined on the Annotator...

Prop	Type (* = required)	Description	Default
taskDescription	*string	Markdown description for what to do in the image.
allowedArea	{ x: number, y: number, w: number, h: number }	Area that is available for annotation.	Entire image.
regionTagList	Array<string>	Allowed "tags" (mutually inclusive classifications) for regions.
regionClsList	Array<string>	Allowed "classes" (mutually exclusive classifications) for regions.
imageTagList	Array<string>	Allowed tags for entire image.
imageClsList	Array<string>	Allowed classes for entire image.
enabledTools	Array<string>	Tools allowed to be used. e.g. "select", "create-point", "create-box", "create-polygon"	Everything.
showTags	boolean	Show tags and allow tags on regions.	true
selectedImage	string	URL of initially selected image.
images	Array<Image>	Array of images to load into annotator
showPointDistances	boolean	Show distances between points.	false
pointDistancePrecision	number	Precision on displayed points (e.g. 3 => 0.123)
theme	"light" | "dark" | Theme	Theme mode (string) or full MUI theme object for styling the component.	"light"
onExit	MainLayoutState => any	Called when "Save" is called.
RegionEditLabel	Node	React Node overriding the form to update the region (see RegionLabel)
allowComments	boolean	Show a textarea to add comments on each annotation.	false
hidePrev	boolean	Hide Previous Image button from the header bar.	false
hideNext	boolean	Hide Next Image button from the header bar.	false
hideClone	boolean	Hide Clone button from the header bar.	false
hideSettings	boolean	Hide Settings button from the header bar.	false
hideFullScreen	boolean	Hide FullScreen/Window button from the header bar.	false
hideSave	boolean	Hide Save button from the header bar.	false

Developers

Development

This project uses Storybook with Vite. To begin developing, run the following commands in the cloned repo:

• npm install (or bun install)
• npm run storybook (or bun run storybook)

A browser tab will automatically open with the project components at http://localhost:9090.

Package Manager

• Primary: npm (recommended)
• Alternative: bun (faster builds)

See more details in the contributing guidelines.

Icons

Consult these icon repositories:

• Material Icons
• Font Awesome Icons