React Image Annotation

Add an annotation layer to an image using the Annotorious React components.

import { Annotorious, ImageAnnotator } from '@annotorious/react';

import '@annotorious/react/annotorious-react.css';

export default function App() {
  return (
    <Annotorious>
      <ImageAnnotator>
        <img src="example.jpg" />
      </ImageAnnotator>
    </Annotorious>
  );
}

Step-by-Step Guide

Import the Annotorious and ImageAnnotator components.

import { Annotorious, ImageAnnotator } from '@annotorious/react';

Import Annotorious base CSS styles.

import '@annotorious/react/annotorious-react.css';

Important: wrap your application with the <Annotatorious> root context tag - other Annotorious components depend on it. You can use Annotorious-provided hooks anywhere below the context tag.

App.tsx
MyAnnotatableImage.tsx

export default function App() {
  return (
    <Annotorious>
      <MyAnnotatableImage />
    </Annotorious>
  );
}

export const MyAnnotatableImage = () => {

  // You can use Annotorious hooks here!
  const annotations = useAnnotations();

  // ...

  return (
    <ImageAnnotator>
      <img src="example.jpg" />
    </ImageAnnotator>
  );
}

Styling

You can apply custom styling to annotations via the style prop. The style can be:

A DrawingStyle object.
A function that receives the ImageAnnotation and the AnnotationState as an input, and returns a DrawingStyle.

const style = (annotation: ImageAnnotation, state: AnnotationState) => ({
  fill: state.hovered ? '#ff0000' : '#ffffff',
  fillOpacity: 0.25
});

<ImageAnnotator style={style}>
  <img src="example.jpg" />
</ImageAnnotator>

Filters

Using a filter, you can dynamically control the visibility of specific annotations, based on their data or external criteria. The filter is a function that receives the ImageAnnotation as an input, and returns a boolean. true makes the annotation visible, false hides it.

const showImportantFilter = (annotation: Annotation) => {
  // Show only if the annotation has an 'important' tag
  return annotation.bodies.some(b => b.purpose === 'tagging' && b.value === 'important');
};

<ImageAnnotator filter={showImportantFilter}>
  <img src="example.jpg" />
</ImageAnnotator>;

Selection Behavior

When a user selects an annotation by click or tap, the default behavior is that the shape will become editable. You can change this behavior through the userSelectAction prop. The prop accepts:

a UserSelectAction object.
a function that receives an ImageAnnotation as input, and returns a UserSelectAction.

A UserSelectAction has one of the three following values.

EDIT: makes the annotation editable, allowing the users to modify its shape (default).
SELECT: clicking an annotation triggers the relevant selection event, but the annotation will not become editable.
NONE: the annotation is inert. Clicking or tapping it has no effect.

import { UserSelectAction } from '@annotorious/react';

// Make all annotations 'read-only'.
<ImageAnnotator userSelectAction={UserSelectAction.SELECT}>
  <img src="example.jpg" />
</ImageAnnotator>

// Function: only allow editing on my own annotation.
const allowEditingMyOwn = (annotation: ImageAnnotation) => {
  const isMine = annotation.target.creator.id == 'me';
  return isMine ? UserSelectAction.EDIT : UserSelectAction.SELECT;
};

<ImageAnnotator userSelectAction={allowEditingMyOwn}>
  <img src="example.jpg" />
</ImageAnnotator>

W3C Format Adapter

A FormatAdapter adds support for different annotation data formats, by introducing crosswalk functionality between Annotorious’ internal annotation data model and other standards.

You can supply a format adapter through the optional adapter prop. Currently, the only available adapter is for the W3C Web Annotation Data Model.

import { Annotorious, ImageAnnotator, W3CImageFormat } from '@annotorious/react';

<Annotorious>
  <ImageAnnotator adapter={W3CImageFormat('example.jpg')}>
    <img src="example.jpg" />
  </ImageAnnotator>
</Annotorious>