Annotating Images

This guide explains how to make an existing image on your webpage annotatable using Annotorious with vanilla JavaScript.

Quick Start

Here’s a basic example to get you started. The code below initializes Annotorious on an existing image, attaches an event listener, and loads annotations from a file.

import { createImageAnnotator } from '@annotorious/annotorious';

// Import essential CSS styles
import '@annotorious/annotorious/annotorious.css';

// Image element ID or DOM element
const anno = createImageAnnotator('sample-image');

// Attach listeners to handle annotation events
anno.on('createAnnotation', function(annotation) {
  console.log('created', annotation);
});

// Load annotations from a JSON file
anno.loadAnnotations('./annotations.json');

Step-by-Step Guide

In your JavaScript file, import createImageAnnotator.

import { createImageAnnotator } from '@annotorious/annotorious';

Important: import the Annotorious CSS stylesheet.

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

Create an annotator instance on your image. You can pass either the ID of the image element, or the DOM element itself.

const anno = createImageAnnotator('sample-image');

// Alternative:
const anno = createImageAnnotator(document.getElementById('sample-image));

Optional: you can pass options to customize the annotator.

const anno = createImageAnnotator('sample-image', {
  drawingEnabled: true,
  style: {
   fill: '#ff0000',
   fillOpacity: 0.25
  }
});

Handle events. Read more about lifecycle events.

anno.on('createAnnotation', (annotation) => {
  console.log('Annotation created:', annotation);
});

anno.on('updateAnnotation', (annotation, previous) => {
  console.log('Annotation updated:', annotation);
});

anno.on('deleteAnnotation', (annotation) => {
  console.log('Annotation deleted:', annotation);
});

Load existing annotations. Read more about the data model on the next page.
```
anno.loadAnnotations('./annotations.json');
```

Script Import

If you are not using a build system, you can include Annotorious via CDN. The createImageAnnotator function is available under the global Annotorious object.

<html>
  <head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@annotorious/annotorious@latest/dist/annotorious.css">
    <script src="https://cdn.jsdelivr.net/npm/@annotorious/annotorious@latest/dist/annotorious.js"></script>
  </head>
  <body>
    <img id="my-image" src="my-image.jpg" />

    <script>
      window.onload = function() {
        var anno = Annotorious.createImageAnnotator('my-image');
      }
    </script>
  </body>
</html>

Working with Annotations

Annotorious provides methods to work with Annotations programmatically:

// Add an annotation to this annotator
anno.addAnnotation({
  id: '7fb76422-3a8c-4c87-bbad-7c8bb68399a0',
  target: {
    selector: {
      type: 'RECTANGLE',
      geometry: {
        bounds: {
            minX: 272,
            minY: 169,
            maxX: 393,
            maxY: 259
        },
        x: 272,
        y: 169,
        w: 121,
        h: 90,
      }
    }
  }
});

By default, Annotorious uses its own native data model, which is optimized for performance and ease of use. However, Annotorious also supports the W3C Web Annotation Data Model. The next section introduces the Annotorious annotation data model in more detail, and explains how to use the W3C Web Annotation format through the W3CImageAdapter.