Annotorious: adding image annotation to a page in a few lines

A factory call, an event listener, and a stylesheet

The quick start is short enough that the whole integration is visible in one screen. The package is installed from npm:

npm install @annotorious/annotorious

Then you create an annotator for an element, load annotations, and listen for user events:

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

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

const anno = createImageAnnotator('image-to-annotate');

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

// Listen to user events
anno.on('createAnnotation', function(annotation) {
  console.log('new annotation', annotation);
});

Three details in that snippet are worth pausing on. The annotator is created with a string, which is the identifier of the image element on the page, so the library attaches itself to the element you already have rather than asking you to manage a container. The stylesheet is imported separately and is not optional, because the annotation overlay has to be positioned over the image and the library does not inject that CSS for you. And the event subscription returns the annotation object directly, so consuming an annotation is a matter of listening for the event and reading a plain value, with no intermediate store to keep in sync.

The package list tells you what the library is aimed at

The workspace configuration is where the shape of the project becomes clear, and it is a list of six packages under the monorepo root. There is a core package, the plain annotorious package that the quick start uses, and then the interesting ones, which are the integrations. There is a package for OpenSeadragon, which is the deep image viewer used for large tiled imagery, a React package, a React package for the manifold integration, and a Svelte package. The presence of a dedicated OpenSeadragon package is the strongest signal about the intended use, because Annotorious was built for scholarly image annotation, where the images are often high resolution and the viewer handles tiling. The React and Svelte packages mean the same annotation core is usable from either framework, and the manifold package suggests an integration with a specific annotation model. The repository topics reinforce that reading, listing image annotation, data annotation tools and IIIF among the tags, with OpenSeadragon and React named as well, and IIIF is the standard for describing and serving cultural heritage images.

A monorepo with per-package builds, and a history under two names

The build setup is a standard npm workspaces arrangement. The root package is the monorepo, the build and test scripts both delegate to the workspaces flag so each package builds and tests itself, and the packages directory holds the six entries listed in the workspace configuration. The root also carries a version update script, which is how a monorepo keeps a version number in step across packages. The repository history behind the package is a little unusual and worth knowing if you are following the links. The repository field in the package metadata points at a different organisation, recogito, while the project itself lives under annotorious, and the description calls the package an Annotorious v3 monorepo. The version in the metadata is 3.9.4, while the recent release tags are v3.4.0 from 2025-05-27, v3.1.0 and v3.0.21 from 2025-01-24, so the monorepo version and the individual package release tags are tracked separately, which is normal for a workspace where each package publishes on its own schedule. The licence is BSD 3-Clause, stated both in the readme and in the package metadata, and the project offers professional support for integration and customisation work alongside its community channels.

Loading and storing annotations

The load method takes a URL rather than an array, which is the detail that shapes how you store data. The call passes a path to a JSON file, and the library fetches it, so the annotations arrive asynchronously and the annotator is usable before they land. That means the shape of the data on disk is the same as the shape of the data the library expects in memory, and an annotation you create in the browser can be serialised straight back to that file without a translation layer. It also means the annotation storage is your problem. The library gives you the annotations and the events, and it gives you the drawing tools, but the persistence, the multi-user merge behaviour and the undo history across sessions are all things you build on top. For a research tool used by one person, a file per image is enough. For a shared annotation platform, you need a backend, and the fact that the API hands you plain objects rather than an internal model makes that backend considerably easier to write. The event callback receives the annotation as an argument, so persisting on create is a matter of serialising and posting that object.

What this library is not

It is worth being explicit about the scope, because the name suggests more than it delivers. Annotorious is a library, not a platform, and the readme offers professional consulting and support for integration, customisation and feature development, which is an admission that customising it is real work. There is no annotation model server, no account system, no review workflow and no dataset management, and the topic list includes data annotation tools because the library is meant to sit inside one. The framework packages are the same story from a different angle, since the React and Svelte entries are wrappers rather than a complete application, and the OpenSeadragon package is the specialised case where the viewer is already handling very large tiled images and the overlay has to keep up with pan and zoom. The project website carries the documentation and the live demos, and the community channels are a discussion forum and an issue tracker, with a note that the individual packages release on their own schedules, so a project depending on more than one of them needs to watch each version.

Editorial conclusion

Annotorious is a good fit for a team that already has an image viewer and needs drawing, rectangles and text annotations on top of it, because the integration is a factory call and an event listener, and because the OpenSeadragon and React packages mean you do not have to reimplement the overlay behaviour yourself. It is the wrong tool if you need a full annotation platform, since this is a library and not a service, and it is the wrong tool if your annotation model is proprietary, since the package list shows wrappers for specific viewer and framework combinations and the core is the piece you would adapt. Before adopting it, read the project website rather than the readme, since the live demos and the documentation live there, and pick the package that matches your stack, because the React, Svelte and OpenSeadragon entries are separate packages with their own release cadence. The project is BSD-3-Clause licensed, the last push was on 2026-10-20, and the monorepo version is 3.9.4.

Frequently asked questions

Official sources

1. annotorious/annotorious on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases