ImageAnnotator

TYPESCRIPT / BROWSER

Live TypeScript example

Try the component here, then use the source below in your application.

Component sizePro v0.2.1 · minified + gzip

JavaScript: 11.5 KiB
Component CSS: 3.2 KiB
Shared theme CSS: 5.5 KiBonce per application

How sizes are measured

The JavaScript figure includes this component’s required helpers. CSS includes its styling dependencies. Each entry is bundled separately for ES2022, minified, then compressed with gzip level 9. Your bundler may share helpers across components. Images, fonts, examples and application code are excluded.

Before compression: JavaScript 30.0 KiB; component CSS 14.3 KiB. These figures describe browser assets, not the complete package download.

View all component measurements →

Preview

Choose a tool and use Add annotation to create marks without dragging. Select a mark in the list to edit its comment and numeric position. Undo, redo and export are buttons.

import '@blukavantui/community/theme.css'

import {createImageAnnotator} from '@blukavantui/pro/image-annotator';
import '@blukavantui/pro/image-annotator.css';
export function mount(host:HTMLElement) {
  const status=document.createElement("p");status.setAttribute("role","status");
  const component=createImageAnnotator(host, {
  "ImageUrl": "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20width%3D%22800%22%20height%3D%22480%22%3E%3Crect%20width%3D%22800%22%20height%3D%22480%22%20fill%3D%22%23f1f5f9%22/%3E%3Cg%20fill%3D%22white%22%20stroke%3D%22%2364748b%22%20stroke-width%3D%223%22%3E%3Crect%20x%3D%2240%22%20y%3D%2280%22%20width%3D%22720%22%20height%3D%22360%22/%3E%3Cpath%20d%3D%22M300%2080v360M550%2080v360M40%20260h260%22/%3E%3C/g%3E%3Cg%20font-family%3D%22sans-serif%22%20font-size%3D%2222%22%20fill%3D%22%231e293b%22%3E%3Ctext%20x%3D%2240%22%20y%3D%2244%22%3EWorkspace%20inspection%3C/text%3E%3Ctext%20x%3D%2290%22%20y%3D%22170%22%3EConference%3C/text%3E%3Ctext%20x%3D%22365%22%20y%3D%22240%22%3EStudio%3C/text%3E%3Ctext%20x%3D%22590%22%20y%3D%22240%22%3EKitchen%3C/text%3E%3C/g%3E%3C/svg%3E",
  Resources:[{Key:"maya",Name:"Maya Chen",Position:"Reviewer",Color:"Purple"}],CurrentUserKey:"maya",
  "Annotations": [
    {
      "Key": "inspection-1", "AuthorKey":"maya", "AuthorName":"Maya Chen",
      "Kind": "Box",
      "X": 0.76,
      "Y": 0.62,
      "Width": 0.16,
      "Height": 0.23,
      "PointsJson": "[]",
      "Text": "Check kitchen ventilation",
      "Color": "Volcano"
    }
  ],
  "IsReadOnly": false,
  "ShowExport": true,
  "ExportFileName": "workspace-inspection",
  "ImageDescription": "Office floor plan showing a conference room, design studio, focus room, storage and kitchen."
}, { SaveRequested: (requestId, annotations) => {
      // Replace browser storage with your API; acknowledge only after it succeeds.
      try {
        localStorage.setItem('bluui-starter:image-annotator', JSON.stringify(annotations));
        queueMicrotask(() => component.update({SaveResultRequestId:requestId, SaveResultSuccess:true, SaveResultMessage:'Saved in this browser.'}));
      } catch {
        queueMicrotask(() => component.update({SaveResultRequestId:requestId, SaveResultSuccess:false, SaveResultMessage:'Save failed. Your edits are retained.'}));
      }
    } });
  host.append(status);
  return {destroy(){component.destroy();status.remove();}};
}

const instance = mount(document.getElementById('example')!)

// When this page or framework component is removed:
// instance.destroy()

Install the library and add the host element

npm install https://blukavantui.blutekmedia.com/downloads/blukavantui-community-0.4.0.tgz
# Install your licensed Pro archive alongside Community
npm install ./blukavantui-pro-0.2.1.tgz

<div id="example"></div>

Download .ts source ↓TypeScript interfaces →Web API reference →Installation guide →

Download Community library ↓Community starter · 9 templates ↓Pro add-on & license →

Connect your application data

Community components use @blukavantui/community. The ten Pro components use the separate @blukavantui/pro add-on alongside Community. Your application handles persistence and authentication through its typed callbacks. Choose the matching edition when installing the example.

Build on your platform

Choose the reference that matches your application.

WEB · TYPESCRIPT

createImageAnnotator

Use Resources and CurrentUserKey for reviewer names and avatars. Every annotation retains AuthorKey, AuthorName and AuthorImageUrl. SaveRequested returns the complete review; store it separately from the original image, acknowledge the matching request, and reload with Annotations plus ResetKey. Box, Arrow, Pin and Freehand have keyboard editing alternatives. Export contains the image, marks and comment cards. Light and dark appearance share the same square editor UI.

v0.2.1

import { createImageAnnotator } from '@blukavantui/pro/image-annotator';
import '@blukavantui/pro/image-annotator.css';

Load @blukavantui/community/theme.css once in your app shell.

createImageAnnotator(host: HTMLElement, options: T.ImageAnnotatorOptions, events?: T.ImageAnnotatorEvents)

Reference for @blukavantui/pro 0.2.1. Required and optional follow the shipped TypeScript declarations; optional does not imply a particular default. Pass typed arrays and objects directly where shown.

Options

Name	Type / requirement	Usage
`Resources`	`BluResource[]`Optional	Reviewer list with Key, Name, ImageUrl, Color and Position.
`CurrentUserKey`	`string`Optional	Author key assigned to new annotations. Author identity must be verified by your server.
`ImageUrl`	`string`Optional	HTTP(S), same-origin relative, blob or image data URL. Export needs a same-origin or CORS-enabled image. Default: "".
`Annotations`	`BluImageAnnotation[]`Required	Normalized annotation list; echo OnAnnotationsChanged.AnnotationsJson back.
`IsReadOnly`	`boolean`Optional	Allows viewing and zooming but prevents annotation changes. Default: False.
`ShowExport`	`boolean`Optional	Shows PNG export when the image is ready. Default: True.
`ExportFileName`	`string`Optional	Base filename for the PNG download. Default: "annotated-image".
`ImageDescription`	`string`Optional	Accessible description of the source image. Default: "Image to annotate".
`SaveResultRequestId`	`string`Optional	Echo the latest OnSaveRequested.RequestId after persistence finishes. Default: "".
`SaveResultSuccess`	`boolean`Optional	True accepts the submitted snapshot; False retains editable changes. Default: False.
`SaveResultMessage`	`string`Optional	Success or failure feedback for the matching request. Default: "".
`ResetKey`	`string`Optional	Change this value to reload the supplied data and discard local history when not saving. Default: "".
`AccessibleLabel`	`string`Optional	Accessible component name; empty uses the component default. Default: "".
`ExtendedClass`	`string`Optional	Additional CSS classes on the Block root. Default: "".

Callbacks

Name	Type / requirement	Usage
`AnnotationsChanged`	`(annotations: T.BluImageAnnotation[]) => void \| Promise<void>`Optional
`SelectionChanged`	`(key: string) => void \| Promise<void>`Optional	Reports the new selection to your application.
`SaveRequested`	`(requestId: string, annotations: T.BluImageAnnotation[]) => void \| Promise<void>`Optional
`Exported`	`(dataUrl: string) => void \| Promise<void>`Optional	PNG with the source image, marks and readable author/comment cards. Source media must allow canvas export.
`Error`	`(message: string) => void \| Promise<void>`Optional

Instance methods & properties

Name	Signature / type	Usage
`element`	`HTMLElement`	Root owned by this instance. Dispose before removing its host.
`update`	`(patch: Partial<T.ImageAnnotatorOptions>) => void`	Apply a partial options update to this instance.
`destroy`	`() => void`	Dispose the instance and its listeners when the view is removed.

Related data types

Expand a type for its fields and allowed values.

BluImageAnnotation

interface BluImageAnnotation {
    AuthorKey?: string;
    AuthorName?: string;
    AuthorImageUrl?: string;
    /** Unique annotation key. */
    Key: string;
    /** Box, Arrow, Pin or Freehand. */
    Kind: "Box" | "Arrow" | "Pin" | "Freehand";
    /** Normalized horizontal start coordinate, from 0 to 1. */
    X?: number;
    /** Normalized vertical start coordinate, from 0 to 1. */
    Y?: number;
    /** Normalized horizontal extent; arrows may use a negative extent. */
    Width?: number;
    /** Normalized vertical extent; arrows may use a negative extent. */
    Height?: number;
    /** Freehand points as an array of {X,Y}, normalized from 0 to 1. */
    PointsJson?: string;
    /** Annotation comment, also available in the accessible list. */
    Text?: string;
    /** Shared ComponentColor code. */
    Color?: ComponentColor;
}

BluResource

interface BluResource {
    /** Stable application-owned person/resource key. */
    Key: string;
    Name: string;
    ImageUrl?: string;
    Color?: ComponentColor;
    /** Role, title or position displayed next to the person. */
    Position?: string;
}

Events0No events yet.View events

Interact with an example to see its events.

Live TypeScript example

createImageAnnotator

Options

Callbacks

Instance methods & properties

Related data types

Purpose and use

Keyboard design guidance

In your application

Search BluKavantUI