Star
Chart primitives
Layouts & specialized
Interactions
SVG utilities
Data utilities
Umbrella package

@visx/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:

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

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

3) 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

npm install --save @visx/annotation

Examples

Annotation
<Annotation />

APIs

#<Annotation />

# childrenReactNoderequired

Annotation children (Subject, Label, Connector)

# dxnumber | undefined

x delta of the Label from the Subject.

# dynumber | undefined

y delta of the Label from the Subject.

# xnumber | undefined

x position of the Subject.

# ynumber | undefined

y position of the Subject.

#<EditableAnnotation />

# childrenReactNoderequired

Annotation children (Subject, Label, Connector)

# heightnumberrequired

Height of the possible drag canvas (e.g., SVG container).

# widthnumberrequired

Width of the possible drag canvas (e.g., SVG container).

# canEditLabelboolean | undefined

Whether the Label position (dx, dy) is editable.

Default true

# canEditSubjectboolean | undefined

Whether the Subject position (x, y) is editable.

Default true

# dxnumber | undefined

x delta of the Label from the Subject.

# dynumber | undefined

y delta of the Label from the Subject.

# labelDragHandlePropsSVGProps<SVGCircleElement> | undefined

Optional circle props to set on the label drag handle.

# onDragEnd(({ x, y, dx, dy, event }: HandlerArgs) => void) | undefined

Callback invoked on drag end.

# onDragMove(({ x, y, dx, dy, event }: HandlerArgs) => void) | undefined

Callback invoked on drag move.

# onDragStart(({ x, y, dx, dy, event }: HandlerArgs) => void) | undefined

Callback invoked on drag start.

# subjectDragHandlePropsSVGProps<SVGCircleElement> | undefined

Optional circle props to set on the subject drag handle.

# xnumber | undefined

x position of the Subject.

# ynumber | undefined

y position of the Subject.

#<CircleSubject />

# classNamestring | undefined

Optional className to apply to CircleSubject in addition to 'visx-annotation-subject'.

# radiusnumber | undefined

Radius of CircleSubject.

Default 16

# strokestring | undefined

Color of CircleSubject.

Default #222

# xnumber | undefined

x position of the Subject.

# ynumber | undefined

y position of the Subject.

#<LineSubject />

# maxnumberrequired

The maximum coordinate of the line.

# minnumberrequired

The minimum coordinate of the line.

# classNamestring | undefined

Optional className to apply to LineSubject in addition to 'visx-annotation-subject'.

# orientation"horizontal" | "vertical" | undefined

Orientation of line.

Default vertical

# strokestring | undefined

Color of LineSubject.

Default #222

# strokeWidthnumber | undefined

strokeWidth of LineSubject.

# xnumber | undefined

x position of LineSubject (for vertical LineSubjects).

# ynumber | undefined

y position of LineSubject (for horizontal LineSubjects).

#<Connector />

# classNamestring | undefined

Optional className to apply to container in addition to 'visx-annotation-connector'.

# dxnumber | undefined

x delta of the Label from the Subject.

# dynumber | undefined

y delta of the Label from the Subject.

# pathPropsSVGProps<SVGPathElement> | undefined

Optional additional props.

# strokestring | undefined

Color of the connector line.

Default #222

# type"line" | "elbow" | undefined

Connector type.

Default elbow

# xnumber | undefined

x position of the Subject.

# ynumber | undefined

y position of the Subject.

#<Label />

# anchorLineStrokestring | undefined

Stroke color of anchor line.

Default #222

# backgroundFillstring | undefined

Background color of label.

Default #eaeaea

# backgroundPaddingnumber | { top?: number | undefined; right?: number | undefined; bottom?: number | undefined; left?: number | undefined; } | undefined

Padding of text from background.

# backgroundPropsSVGProps<SVGRectElement> | undefined

Additional props to be passed to background SVGRectElement.

# classNamestring | undefined

Optional className to apply to container in addition to 'visx-annotation-label'.

# fontColorstring | undefined

Color of title and subtitle text.

Default #222

# horizontalAnchor"end" | "middle" | "inherit" | "start" | undefined

Whether the label is horizontally anchored to the start, middle, or end of its x position.

# maxWidthnumber | undefined

Max width of annotation, including background, for text wrapping.

Default 125

# resizeObserverPolyfill(new (cb: ResizeObserverCallback) => ResizeObserver) | undefined

Optionally inject a ResizeObserver polyfill, else this must be globally available.

# showAnchorLineboolean | undefined

Whether to render a line indicating label text anchor.

Default true

# showBackgroundboolean | undefined

Whether to render a label background.

Default true

# subtitlestring | undefined

Optional subtitle.

# subtitleDynumber | undefined

The vertical offset of the subtitle from the title.

Default 4

# subtitleFontSizestring | number | undefined

Optional title font size.

Default 12

# subtitleFontWeightstring | number | undefined

Optional title font weight.

Default 200

# subtitlePropsPartial<TextProps> | undefined

Optional subtitle Text props (to override color, etc.).

# titlestring | undefined

Optional title.

# titleFontSizestring | number | undefined

Optional title font size.

Default 16

# titleFontWeightstring | number | undefined

Optional title font weight.

Default 600

# titlePropsPartial<TextProps> | undefined

Optional title Text props (to override color, etc.).

# verticalAnchor"end" | "middle" | "start" | undefined

Whether the label is vertically anchored to the start, middle, or end of its y position.

# widthnumber | undefined

Width of annotation, including background, for text wrapping.

# xnumber | undefined

Left offset of entire AnnotationLabel, if not specified uses x + dx from Annotation.

# ynumber | undefined

Top offset of entire AnnotationLabel, if not specified uses y + dy from Annotation.

#<HtmlLabel />

# anchorLineStrokestring | undefined

Stroke color of anchor line.

Default #222

# childrenReactNode

Pass in a custom element as the label to style as you like. Renders inside a <foreignObject>, be aware that most non-browser SVG renderers will not render HTML <foreignObject>s. See: https://github.com/airbnb/visx/issues/1173#issuecomment-1014380545.

# classNamestring | undefined

Optional className to apply to container in addition to 'visx-annotation-label'.

# containerStyleCSSProperties | undefined

Optional styles to apply to the HTML container.

# horizontalAnchor"end" | "middle" | "inherit" | "start" | undefined

Whether the label is horizontally anchored to the start, middle, or end of its x position.

# resizeObserverPolyfill(new (cb: ResizeObserverCallback) => ResizeObserver) | undefined

Optionally inject a ResizeObserver polyfill, else this must be globally available.

# showAnchorLineboolean | undefined

Whether to render a line indicating label text anchor.

Default true

# verticalAnchor"end" | "middle" | "start" | undefined

Whether the label is vertically anchored to the start, middle, or end of its y position.

# xnumber | undefined

Left offset of entire AnnotationLabel, if not specified uses x + dx from Annotation.

# ynumber | undefined

Top offset of entire AnnotationLabel, if not specified uses y + dy from Annotation.

#<LinePathAnnotation />

# classNamestring | undefined

Add a class name to the line path.

# labelstring | undefined

The text for your label.

# labelAnchor"end" | "middle" | "start" | undefined

The label's textAnchor.

Default middle

# labelDxnumber | undefined

The x-coordinate shift to the label.

Default 0

# labelDynumber | undefined

The y-coordinate shift to the label

Default 0

# labelFillstring | undefined

The color of label. Defaults to props.stroke.

# labelFontSizenumber | undefined

The font size of the label text.

Default 10

# labelPaintOrderstring | undefined

The label's SVG paint-order.

Default stroke

# labelStrokestring | undefined

The color of the label.

Default white

# labelStrokeWidthnumber | undefined

The stroke width of the label text.

Default 3

# leftnumber | undefined

A left pixel offset applied to the entire bar group.

Default 0

# points(Point | SimplePoint)[] | undefined

An array of points describing the line path.

Default []

# strokestring | undefined

The color of the line.

Default black

# strokeWidthnumber | undefined

The pixel width of the line.

Default 1

# topnumber | undefined

A top pixel offset applied to the entire bar group.

Default 0

Exports