ImageAnnotator

TYPESCRIPT / BROWSER

Live TypeScript example

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

Component sizev0.6.2 · minified + gzip

JavaScript: 7.7 KiB
Component CSS: 1.5 KiB
Shared theme CSS: 3.8 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 20.2 KiB; component CSS 5.8 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/web/theme.css'

import {createImageAnnotator} from '@blukavantui/web/image-annotator';
import '@blukavantui/web/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",
  "Annotations": [
    {
      "Key": "inspection-1",
      "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-web-0.6.2.tgz

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

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

Download TypeScript library · 825.6 KiB ↓Download starter project · 907.6 KiB ↓

Connect your application data

This example uses the downloadable @blukavantui/web package. Your application handles persistence and authentication through its typed callbacks. The starter ZIP includes this same example.

Build on your platform

Choose the reference that matches your application.

WEB · TYPESCRIPT

createImageAnnotator

Pass options as the second argument and callbacks in the third argument. Keep the returned instance to update options or dispose it when its view is removed.

v0.6.2

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

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

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

Reference for @blukavantui/web 0.6.2. 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
`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
`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 {
    /** 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;
}

ComponentColor

type ComponentColor = typeof componentColors[number];

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