API Reference

Factory Function

TypeScript

annotate(img: HTMLImageElement, options?: Partial<AnnotateImageOptions>): AnnotateImage

Creates an annotation layer on an image element. Returns an AnnotateImage instance. When using the IIFE bundle (core.min.js), call via AnnotateImage.annotate().

Options

Option	Type	Default	Description
`editable`	`boolean`	`true`	Enable annotation editing
`notes`	`AnnotationNote[]`	`[]`	Initial annotations
`api`	`AnnotateApi`	—	Server persistence config
`labels`	`Labels`	defaults	UI label overrides
`onChange`	`(notes: NoteData[]) => void`	—	Called after any notes mutation
`onSave`	`(note: NoteData) => void`	—	Called after a note is saved
`onDelete`	`(note: NoteData) => void`	—	Called after a note is deleted
`onLoad`	`(notes: NoteData[]) => void`	—	Called after notes are loaded
`autoResize`	`boolean`	`true`	Re-scale annotations on window resize via ResizeObserver
`onError`	`(ctx: AnnotateErrorContext) => void`	`console.error`	Called on API errors

AnnotateApi

Each field accepts a URL string (default fetch behavior) or a function for full control. Omit api entirely for static-only mode.

TypeScript

interface AnnotateApi {
  load?: string | (() => Promise<AnnotationNote[]>);
  save?: string | ((note: NoteData) => Promise<SaveResult>);
  delete?: string | ((note: NoteData) => Promise<void>);
}

When URLs are provided: load performs a GET request; save sends a POST with a JSON body and expects { annotation_id?: string } in the response; delete sends a POST with a JSON body.

Labels

Field	Type	Default
`addNote`	`string`	`"Add Note"`
`save`	`string`	`"OK"`
`delete`	`string`	`"Delete"`
`cancel`	`string`	`"Cancel"`
`placeholder`	`string`	`""`

Instance Methods

Method	Returns	Description
`add()`	`boolean`	Enter add-note mode. Returns false if already editing.
`clear()`	`void`	Remove all annotations and rebuild views.
`destroy()`	`void`	Tear down completely. Idempotent.
`getNotes()`	`NoteData[]`	Get current annotations (internal fields stripped).
`load()`	`void`	Rebuild views from the current notes array.
`setNotes(notes)`	`void`	Replace all annotations (no callbacks fired).
`setEditable(bool)`	`void`	Toggle editing mode globally.

Data Types

AnnotationNote

TypeScript

interface AnnotationNote {
  id: string;
  top: number;
  left: number;
  width: number;
  height: number;
  text: string;
  editable: boolean;
}

NoteData

Passed to callbacks — internal fields stripped:

TypeScript

type NoteData = Omit<AnnotationNote, 'view' | 'editable'>;

SaveResult

TypeScript

interface SaveResult {
  annotation_id?: string;
}

AnnotateErrorContext

TypeScript

interface AnnotateErrorContext {
  type: 'load' | 'save' | 'delete';
  error: Error;
  note?: AnnotationNote;
}

CSS Classes

Class	Description
`.image-annotate-canvas`	Main container wrapping the image
`.image-annotate-view`	View overlay displaying annotations
`.image-annotate-edit`	Edit overlay with form controls
`.image-annotate-area`	Individual annotation region
`.image-annotate-note`	Tooltip/popover showing annotation text
`.image-annotate-add`	"Add Note" button
`.image-annotate-area-editable`	Applied to editable annotation areas
`.image-annotate-editing`	Applied to canvas during edit mode