annotation

SVG Annotations enable you to label points, thresholds, or regions of a visualization to provide additional context to for your chart consumer. This package is heavily inspired by Susie Lu's react-annotation library.

Each annotation consists of three (optional) parts:

Subject (CircleSubject, LineSubject, more 🔜) – what part of a chart is being annotated (point, line, region)

Label – the text component for the annotation. Handles SVG text wrapping using @tealess/viz-text, and supports title and subtitle customization as well as vertical & horizontal anchors / alignment

Connector – line connecting a subject and label

The Annotation or EditableAnnotation component wrappers allow you to compose these components and simplify their individual positioning:

<EditableAnnotation
  x={subjectX}
  y={subjectY}
  dx={labelDx} // x offset of label from subject
  dy={labelDy} // y offset of label from subject
  onDragEnd={({ x, y, dx, dy }) => ...}
>
  <Connector />
  <CircleSubject />
  <Label title="Context about this point" subtitle="More deets">
</EditableAnnotation>

Components can also be used in isolation, in which case you must specify exact positions for each item:

() => (
  <g>
    <Connector x={subjectX} y={subjectY} dx={labelDx} dy={labelDy} />
    <CircleSubject x={subjectX} y={subjectY} />
    <Label x={subjectX + labelDx} y={subjectY + labelDy} title="...">
  </g>
)

⚠️ ResizeObserver dependency

The Label component relies on ResizeObservers for auto-sizing. If you need a polyfill, you can either polute the window object or inject it cleanly through props:

import { ResizeObserver } from 'your-favorite-polyfill';

function App() {
  return <Label resizeObserverPolyfill={ResizeObserver} {...} />
}

Installation

bun add @tealess/viz-annotation

APIs