@postnikdaniil/vue-annotator

Dev-only visual annotation tool for Vue 2.7+ / Vue 3 apps. Click any element, leave a comment, export as markdown. No server required — everything stays in localStorage.

Install

npm install @postnikdaniil/vue-annotator

Quick Start

Plugin (recommended)

Auto-mounts the toolbar into document.body:

// main.ts
import { createApp } from 'vue'
import { VueAnnotatorPlugin } from '@postnikdaniil/vue-annotator'
import App from './App.vue'

const app = createApp(App)

if (import.meta.env.DEV) {
  app.use(VueAnnotatorPlugin)
}

app.mount('#app')

Component

If you need more control over placement:

<script setup>
import { VueAnnotator } from '@postnikdaniil/vue-annotator'
</script>

<template>
  <VueAnnotator />
</template>

Vue 2.7

Works the same way via vue-demi:

// main.js
import Vue from 'vue'
import { VueAnnotatorPlugin } from '@postnikdaniil/vue-annotator'

if (process.env.NODE_ENV === 'development') {
  Vue.use(VueAnnotatorPlugin)
}

How It Works

1. Click the inspect button (target icon) in the toolbar
2. Hover over any element — it highlights with component name tooltip
3. Click an element to select it
4. Type your annotation in the popup, press Cmd/Ctrl+Enter or click Add
5. Numbered markers appear on annotated elements
6. Click Export to copy all annotations as markdown

Toolbar Buttons

| Button | Action | |--------|--------| | Target | Toggle inspect mode | | Clipboard | Export annotations to clipboard as markdown | | Trash | Clear all annotations on current page | | Minus | Hide toolbar (click eye icon to restore) |

Keyboard Shortcuts

• Escape — cancel inspect mode or close popup
• Cmd/Ctrl+Enter — submit annotation

Export Format

Annotations are exported as markdown:

## Annotations (2)

1. <ProductCard> (div.product-card, section.catalog > div.product-card:nth-child(1)): "increase bottom padding"
2. <AddToCartButton> (button.btn-primary "Buy", div.product > button.btn-primary): "make it green"

Each line includes: component name, element description, CSS selector, and your comment.

Features

• Vue 2.7+ and Vue 3 — uses vue-demi for compatibility
• Component detection — shows Vue component names and hierarchy (<App> -> <ProductPage> -> <AddToCartButton>)
• Unique selectors — generates CSS selectors with :nth-child() for disambiguation
• localStorage persistence — annotations survive page reload
• SPA navigation — annotations are scoped per route (pathname + hash)
• Detached annotations — if an annotated element disappears from DOM, annotations are shown in a separate panel
• Self-contained — CSS-in-JS, no external stylesheets needed
• Dev-only — designed to be tree-shaken in production builds

API

Exports

import { VueAnnotator, VueAnnotatorPlugin } from '@postnikdaniil/vue-annotator'
import type { Annotation, InspectorTarget } from '@postnikdaniil/vue-annotator'

VueAnnotatorPlugin

Vue plugin. Call app.use(VueAnnotatorPlugin) to auto-mount the toolbar.

VueAnnotator

The toolbar Vue component. Use directly if you need manual control over mounting.

Types

interface Annotation {
  id: string
  comment: string
  element: string        // "button.btn-primary"
  elementPath: string    // unique CSS selector
  componentName: string  // "<AddToCartButton>"
  componentChain: string // "<App> -> <ProductPage> -> <AddToCartButton>"
  timestamp: number
}

interface InspectorTarget {
  el: HTMLElement
  element: string
  elementPath: string
  componentName: string
  componentChain: string
  rect: DOMRect
}

Requirements

• Vue >= 2.7 or Vue >= 3.0
• Browser with localStorage support
• Dev mode only — Vue component detection relies on internal properties (__vueParentComponent, __vue__) that are stripped in production builds

License

MIT