Data utilities
Umbrella package
@visx/annotation
SVG Annotation
s 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 ResizeObserver
s 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 />
APIs
#<Annotation />
Annotation children (Subject, Label, Connector)
number | undefined
x delta of the Label from the Subject.
number | undefined
y delta of the Label from the Subject.
number | undefined
x position of the Subject.
number | undefined
y position of the Subject.
#<EditableAnnotation />
Annotation children (Subject, Label, Connector)
Height of the possible drag canvas (e.g., SVG container).
Width of the possible drag canvas (e.g., SVG container).
boolean | undefined
Whether the Label position (dx, dy) is editable.
Default true
boolean | undefined
Whether the Subject position (x, y) is editable.
Default true
number | undefined
x delta of the Label from the Subject.
number | undefined
y delta of the Label from the Subject.
SVGProps<SVGCircleElement> | undefined
Optional circle props to set on the label drag handle.
(({ x, y, dx, dy, event }: HandlerArgs) => void) | undefined
Callback invoked on drag end.
(({ x, y, dx, dy, event }: HandlerArgs) => void) | undefined
Callback invoked on drag move.
(({ x, y, dx, dy, event }: HandlerArgs) => void) | undefined
Callback invoked on drag start.
SVGProps<SVGCircleElement> | undefined
Optional circle props to set on the subject drag handle.
number | undefined
x position of the Subject.
number | undefined
y position of the Subject.
#<CircleSubject />
string | undefined
Optional className to apply to CircleSubject in addition to 'visx-annotation-subject'.
number | undefined
Radius of CircleSubject.
Default 16
string | undefined
Color of CircleSubject.
Default #222
number | undefined
x position of the Subject.
number | undefined
y position of the Subject.
#<LineSubject />
The maximum coordinate of the line.
The minimum coordinate of the line.
string | undefined
Optional className to apply to LineSubject in addition to 'visx-annotation-subject'.
"horizontal" | "vertical" | undefined
Orientation of line.
Default vertical
string | undefined
Color of LineSubject.
Default #222
number | undefined
strokeWidth of LineSubject.
number | undefined
x position of LineSubject (for vertical LineSubjects).
number | undefined
y position of LineSubject (for horizontal LineSubjects).
#<Connector />
string | undefined
Optional className to apply to container in addition to 'visx-annotation-connector'.
number | undefined
x delta of the Label from the Subject.
number | undefined
y delta of the Label from the Subject.
SVGProps<SVGPathElement> | undefined
Optional additional props.
string | undefined
Color of the connector line.
Default #222
"line" | "elbow" | undefined
Connector type.
Default elbow
number | undefined
x position of the Subject.
number | undefined
y position of the Subject.
#<Label />
string | undefined
Stroke color of anchor line.
Default #222
string | undefined
Background color of label.
Default #eaeaea
number | { top?: number | undefined; right?: number | undefined; bottom?: number | undefined; left?: number | undefined; } | undefined
Padding of text from background.
SVGProps<SVGRectElement> | undefined
Additional props to be passed to background SVGRectElement.
string | undefined
Optional className to apply to container in addition to 'visx-annotation-label'.
string | undefined
Color of title and subtitle text.
Default #222
"end" | "middle" | "inherit" | "start" | undefined
Whether the label is horizontally anchored to the start, middle, or end of its x position.
number | undefined
Max width of annotation, including background, for text wrapping.
Default 125
(new (cb: ResizeObserverCallback) => ResizeObserver) | undefined
Optionally inject a ResizeObserver polyfill, else this must be globally available.
boolean | undefined
Whether to render a line indicating label text anchor.
Default true
boolean | undefined
Whether to render a label background.
Default true
string | undefined
Optional subtitle.
number | undefined
The vertical offset of the subtitle from the title.
Default 4
string | number | undefined
Optional title font size.
Default 12
string | number | undefined
Optional title font weight.
Default 200
Partial<TextProps> | undefined
Optional subtitle Text props (to override color, etc.).
string | undefined
Optional title.
string | number | undefined
Optional title font size.
Default 16
string | number | undefined
Optional title font weight.
Default 600
Partial<TextProps> | undefined
Optional title Text props (to override color, etc.).
"end" | "middle" | "start" | undefined
Whether the label is vertically anchored to the start, middle, or end of its y position.
number | undefined
Width of annotation, including background, for text wrapping.
number | undefined
Left offset of entire AnnotationLabel, if not specified uses x + dx from Annotation.
number | undefined
Top offset of entire AnnotationLabel, if not specified uses y + dy from Annotation.
#<HtmlLabel />
string | undefined
Stroke color of anchor line.
Default #222
ReactNode
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.
string | undefined
Optional className to apply to container in addition to 'visx-annotation-label'.
CSSProperties | undefined
Optional styles to apply to the HTML container.
"end" | "middle" | "inherit" | "start" | undefined
Whether the label is horizontally anchored to the start, middle, or end of its x position.
(new (cb: ResizeObserverCallback) => ResizeObserver) | undefined
Optionally inject a ResizeObserver polyfill, else this must be globally available.
boolean | undefined
Whether to render a line indicating label text anchor.
Default true
"end" | "middle" | "start" | undefined
Whether the label is vertically anchored to the start, middle, or end of its y position.
number | undefined
Left offset of entire AnnotationLabel, if not specified uses x + dx from Annotation.
number | undefined
Top offset of entire AnnotationLabel, if not specified uses y + dy from Annotation.
#<LinePathAnnotation />
string | undefined
Add a class name to the line path.
string | undefined
The text for your label.
"end" | "middle" | "start" | undefined
The label's textAnchor.
Default middle
number | undefined
The x-coordinate shift to the label.
Default 0
number | undefined
The y-coordinate shift to the label
Default 0
string | undefined
The color of label. Defaults to props.stroke.
number | undefined
The font size of the label text.
Default 10
string | undefined
The label's SVG paint-order.
Default stroke
string | undefined
The color of the label.
Default white
number | undefined
The stroke width of the label text.
Default 3
number | undefined
A left pixel offset applied to the entire bar group.
Default 0
(Point | SimplePoint)[] | undefined
An array of points describing the line path.
Default []
string | undefined
The color of the line.
Default black
number | undefined
The pixel width of the line.
Default 1
number | undefined
A top pixel offset applied to the entire bar group.
Default 0