Annotating An Image In JavaScript – Annotorious

Category: Image , Javascript , Recommended | October 14, 2020
Views Total:22 views
Official Page:Go to website
Last Update:October 14, 2020


Annotating An Image In JavaScript – Annotorious


Annotorious is a simple yet feature-rich JavaScript image annotation library that adds custom comments, notes, tags to a specific part of an image.


  • Load pre-defined annotations from a JSON file.
  • Drag and drop to create new annotations from an editor popup.
  • Based on W3C WebAnnotation model.

How to use it:

1. Install and import the Annotorious as a module.

$ npm install @recogito/annotorious --save
import { Annotorious } from '@recogito/annotorious';

2. Or download the package and insert the annotorious.min.js into the HTML document.

<link rel="annotorious.min.css" href="styles.css" />
<script src="annotorious.min.js"></script>

3. Initialize the Annotorious on the image and we’re ready to go.

<img id="example" src="example.jpg" />
var anno = Annotorious.init({
    image: 'example'

4. Define your annotations in a w3c.json file and load it on page load.

// annotations.w3c.json
    "@context": "",
    "id": "#unique-ID-Here",
    "type": "Annotation",
    "body": [{
      "type": "TextualBody",
      "value": "Comments Here"
    }, {
      "type": "TextualBody",
      "purpose": "tagging",
      "value": "Tag 1"
    }, {
      "type": "TextualBody",
      "purpose": "tagging",
      "value": "Tag 2"
    "target": {
      "selector": [{
        "type": "FragmentSelector",
        "conformsTo": "",
        "value": "xywh=pixel:270,120,90,170"

3. Enable read-only mode. Defaults to false.

var anno = Annotorious.init({
    image: 'example',
    readOnly: true

4. Disable the editor popup. Defaults to false.

var anno = Annotorious.init({
    image: 'example',
    headless: true

5. Add a new annotation to the image following the structure you’ve seen in the annotations.w3c.json.

// add an annotation
anno.addAnnotation(annotation [, readOnly]);

// add an array of annotations

6. Remove an annotation from the image.


7. Get all annotations.


8. Select an annotation.

// select the current annotation

// select a specific annotation

9. Show/hide the annotations.


10. Apply a custom template to the annotation.

anno.applyTemplate(template, openEditor[TRUE/FALSE]);

11. Destroy the instance.


12. Event handlers.

anno.on('selectAnnotation', function(annotation) {
  console.log('selected', annotation);

anno.on('createAnnotation', function(a) {
  console.log('created', a);

anno.on('updateAnnotation', function(annotation, previous) {
  console.log('updated', previous, 'with', annotation);

anno.on('deleteAnnotation', function(annotation) {
  console.log('deleted', annotation);

anno.on('mouseEnterAnnotation', function(annotation, event) {
  console.log('mouseEnter', annotation);

anno.on('mouseLeaveAnnotation', function(annotation, event) {
  console.log('mouseLeave', annotation);


v2.1.3 (10/14/2020)

  • Dim mask now also available for the polygon drawing tool
  • Czech UI translation
  • Tag widget: fixed broken autosuggest behavior
  • Editor plugins: config params are now properly forwarded to plugin args

v2.1.2 (09/22/2020)

  • Environment is no longer a global object, meaning that it is now safe to use multiple Recogito/Annotorious instances on the same page
  • All CSS classes are now properly prefixed to avoid clashes with other styles on the page (either with a9s for Annotorious-specific elements or r6o for elements imported from Recogito core
  • Small bugfixes to the dim mask

v2.1.1 (09/20/2020)

  • CSS styles are no longer embedded in the JavaScript file, but now have to be imported separately.
  • Editor widgets are becoming more flexible. This release is the first to include beta support for a plugin API. As a consequence, this version introduces a minimal change to how the tag widget is configured with a controlled vocabulary.

v2.0.8 (09/13/2020)

  • Minor bugfix

v2.0.7 (08/29/2020)

  • IE11 support bugfixes

v2.0.6 (08/29/2020)

  • IE11 compatibility
  • Editable polygon shapes
  • Bugfixes concerning the behavior of the tag autosuggest component
  • Security fixes for library dependencies

v2.0.5 (07/12/2020)

  • Added babel polyfill (IE11 compat)

v2.0.4 (07/12/2020)

  • Beta support for rendering any SVG shape contained in W3C Web Annotations
  • Beta support for polygon drawing
  • Various bugfixes
  • Portuguese UI translation
  • Tag widget: controlled vocabulary autosuggest
  • Selecting an annotation now adds a selected CSS class

v2.0.3 (06/12/2020)

  • Various smaller bugfixes
  • Microsoft Edge compatibility
  • Experimental support for responsive images
  • Web Annotation standard compliance: target now includes a source property with the image source URL
  • Minor API changes: selectAnnotation method now returns selected annotation object and does not fire the selectAnnotation event
  • Added support for internationalization
  • Ability to handle user information for UI display and when creating/updating annotations
  • Ability to add created and modified timestamps, with an option for the host application to sync with the server time

v2.0.2 (05/21/2020)

  • Minor bugfixes
  • Enabling readOnly annotations

v2.0.2 (05/21/2020)

  • Minor bugfixes

You Might Be Interested In:

Leave a Reply