@hanieldaniel/img-marker

A framework-agnostic TypeScript library for image annotation. Capture screenshots, annotate with drawing tools, and export the result as a PNG blob — all inside a Shadow DOM modal that works in any web app.

---

Install

npm install @hanieldaniel/img-marker

---

Quick start

import { Annotator } from '@hanieldaniel/img-marker'

const annotator = new Annotator()

annotator.on('save', (blob) => {
  // flat PNG blob — do whatever you need
  const url = URL.createObjectURL(blob)
  const a = document.createElement('a')
  a.href = url
  a.download = 'annotated.png'
  a.click()
  annotator.close()
})

annotator.on('cancel', () => {
  annotator.close()
})

// open from a file input
document.querySelector('#file-input').addEventListener('change', (e) => {
  const file = (e.target as HTMLInputElement).files![0]
  annotator.open({ type: 'file', file })
})

---

Image sources

From a file

import { Annotator, openFilePicker } from '@hanieldaniel/img-marker'

const file = await openFilePicker()
annotator.open({ type: 'file', file })

From a screenshot

annotator.open({ type: 'screenshot' })

Opens a fullscreen overlay; the user drags a region to capture. Internally uses html2canvas. Cross-origin content may not capture.

From camera

annotator.open({ type: 'camera' })

Requests getUserMedia video permission, shows a preview, and lets the user capture a frame.

---

Annotation tools

Tools appear in the toolbar in this order:

Tool	Description
rect	Rectangle / bounding box
arrow	Arrow with filled head
text	Text label (click to place, Enter to commit)
blur	Pixel blur / redact region
ellipse	Ellipse / circle

---

Tool style options

Each annotation uses the currently active style:

Property	Type	Description
color	string	Fill color (CSS color string)
fillAlpha	number	Fill opacity (0–1, applies to rect and ellipse)
strokeColor	string	Stroke / border color
strokeWidth	number	Stroke width in pixels (1–20)
opacity	number	Global annotation opacity (0–1)
fontSize	number	Font size in pixels (text tool)
radius	number	Blur radius in pixels (blur tool)

---

Events

annotator.on('save', (blob: Blob) => { })      // user clicked Save
annotator.on('cancel', () => { })              // user clicked Cancel
annotator.on('tool-change', (tool) => { })     // active tool changed
annotator.on('style-change', (style) => { })   // any style property changed

annotator.off('save', handler)                 // remove a specific listener

The modal does not close itself — call annotator.close() inside your save / cancel handlers.

---

Configuration

const annotator = new Annotator({
  // show only a subset of tools, in your preferred order
  toolbar: [
    { tool: 'rect' },
    { tool: 'arrow' },
    { tool: 'text' },
    { tool: 'blur', hidden: true },  // hidden but still accessible via selectTool()
  ],

  // override default style values
  defaultStyle: {
    strokeColor: '#facc15',
    strokeWidth: 3,
    opacity: 0.9,
  },

  // set true when providing your own toolbar HTML
  customToolbar: true,
})

---

Custom toolbar

When customToolbar: true the built-in toolbar is not rendered. Build your own UI and bind it to the annotator's imperative API:

const annotator = new Annotator({ customToolbar: true })

// tool selection
document.querySelector('#btn-rect').addEventListener('click', () => annotator.selectTool('rect'))
document.querySelector('#btn-arrow').addEventListener('click', () => annotator.selectTool('arrow'))
document.querySelector('#btn-text').addEventListener('click', () => annotator.selectTool('text'))
document.querySelector('#btn-blur').addEventListener('click', () => annotator.selectTool('blur'))
document.querySelector('#btn-ellipse').addEventListener('click', () => annotator.selectTool('ellipse'))

// style controls
document.querySelector('#color').addEventListener('input', (e) =>
  annotator.setColor((e.target as HTMLInputElement).value))

document.querySelector('#stroke-color').addEventListener('input', (e) =>
  annotator.setStrokeColor((e.target as HTMLInputElement).value))

document.querySelector('#stroke-width').addEventListener('input', (e) =>
  annotator.setStrokeWidth(Number((e.target as HTMLInputElement).value)))

document.querySelector('#opacity').addEventListener('input', (e) =>
  annotator.setOpacity(Number((e.target as HTMLInputElement).value)))

// undo / redo
document.querySelector('#undo').addEventListener('click', () => annotator.undo())
document.querySelector('#redo').addEventListener('click', () => annotator.redo())

// react to state changes to keep your UI in sync
annotator.on('tool-change', (tool) => {
  document.querySelectorAll('[data-tool]').forEach((el) =>
    el.classList.toggle('active', el.dataset.tool === tool))
})

---

Imperative API

annotator.open(source)           // open modal and load image
annotator.close()                // close modal (call from save/cancel handlers)
annotator.selectTool(tool)       // 'rect' | 'arrow' | 'text' | 'blur' | 'ellipse'
annotator.setColor(color)        // fill color
annotator.setFillAlpha(alpha)    // fill opacity (0–1)
annotator.setStrokeColor(color)  // stroke color
annotator.setStrokeWidth(n)      // stroke width (px)
annotator.setOpacity(n)          // global opacity (0–1)
annotator.setFontSize(n)         // font size in px (text tool)
annotator.setRadius(n)           // blur radius in px (blur tool)
annotator.getSelected()          // returns selected annotation id or null
annotator.setSelected(id)        // programmatically select an annotation
annotator.deleteSelected()       // delete the currently selected annotation
annotator.undo()                 // undo last annotation
annotator.redo()                 // redo
annotator.zoomIn()               // increase zoom by 0.25
annotator.zoomOut()              // decrease zoom by 0.25
annotator.on(event, handler)
annotator.off(event, handler)

Keyboard shortcuts

Shortcut	Action
Ctrl+Z / ⌘Z	Undo
Ctrl+Y / ⌘⇧Z	Redo
Enter	Commit text input
Escape	Cancel in-progress annotation / deselect tool / deselect annotation
Delete / Backspace	Delete selected annotation

---

Zoom behaviour

When an image is opened, the initial zoom is automatically calculated so that images larger than the modal fit within view (zoom-out only). Small images display at their natural size (zoom = 1). The user can then zoom in or out using the toolbar buttons (range: 0.25×–4×).

---

Framework examples

React

import { useEffect, useRef } from 'react'
import { Annotator } from '@hanieldaniel/img-marker'

export function AnnotateButton({ file }: { file: File }) {
  const annotatorRef = useRef<Annotator | null>(null)

  useEffect(() => {
    const annotator = new Annotator()
    annotator.on('save', (blob) => {
      console.log('got blob', blob)
      annotator.close()
    })
    annotator.on('cancel', () => annotator.close())
    annotatorRef.current = annotator
    return () => annotator.close()
  }, [])

  return (
    <button onClick={() => annotatorRef.current?.open({ type: 'file', file })}>
      Annotate
    </button>
  )
}

Vue

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue'
import { Annotator } from '@hanieldaniel/img-marker'

const annotator = new Annotator()

onMounted(() => {
  annotator.on('save', (blob) => { console.log(blob); annotator.close() })
  annotator.on('cancel', () => annotator.close())
})
onUnmounted(() => annotator.close())
</script>

<template>
  <button @click="annotator.open({ type: 'screenshot' })">Capture & Annotate</button>
</template>

Vanilla JS (CDN, coming soon)

<script type="module">
  import { Annotator } from 'https://cdn.jsdelivr.net/npm/@hanieldaniel/img-marker/dist/index.js'
  const annotator = new Annotator()
  // ...
</script>

---

Browser support

Modern evergreen browsers (Chrome, Firefox, Safari, Edge). No IE11. Client-side only — does not run in SSR/Node.

---

License

MIT