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:
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@visx/text
, and supportstitle
andsubtitle
customization as well as vertical & horizontal anchors / alignmentConnector
โ 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
x delta of the Label from the Subject.
number
y delta of the Label from the Subject.
number
x position of the Subject.
number
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
Whether the Label position (dx, dy) is editable.
Default true
boolean
Whether the Subject position (x, y) is editable.
Default true
number
x delta of the Label from the Subject.
number
y delta of the Label from the Subject.
SVGProps<SVGCircleElement>
Optional circle props to set on the label drag handle.
({ x, y, dx, dy, event }: HandlerArgs) => void
Callback invoked on drag end.
({ x, y, dx, dy, event }: HandlerArgs) => void
Callback invoked on drag move.
({ x, y, dx, dy, event }: HandlerArgs) => void
Callback invoked on drag start.
SVGProps<SVGCircleElement>
Optional circle props to set on the subject drag handle.
number
x position of the Subject.
number
y position of the Subject.
#<CircleSubject />
string
Optional className to apply to CircleSubject in addition to 'visx-annotation-subject'.
number
Radius of CircleSubject.
Default 16
string
Color of CircleSubject.
Default #222
number
x position of the Subject.
number
y position of the Subject.
#<LineSubject />
The maximum coordinate of the line.
The minimum coordinate of the line.
string
Optional className to apply to LineSubject in addition to 'visx-annotation-subject'.
"horizontal" | "vertical"
Orientation of line.
Default vertical
string
Color of LineSubject.
Default #222
number
strokeWidth of LineSubject.
number
x position of LineSubject (for vertical LineSubjects).
number
y position of LineSubject (for horizontal LineSubjects).
#<Connector />
string
Optional className to apply to container in addition to 'visx-annotation-connector'.
number
x delta of the Label from the Subject.
number
y delta of the Label from the Subject.
SVGProps<SVGPathElement>
Optional additional props.
string
Color of the connector line.
Default #222
"line" | "elbow"
Connector type.
Default elbow
number
x position of the Subject.
number
y position of the Subject.
#<Label />
string
Stroke color of anchor line.
Default #222
string
Background color of label.
Default #eaeaea
number | { top?: number; right?: number; bottom?: number; left?: number; }
Padding of text from background.
SVGProps<SVGRectElement>
Additional props to be passed to background SVGRectElement.
string
Optional className to apply to container in addition to 'visx-annotation-label'.
string
Color of title and subtitle text.
Default #222
"end" | "middle" | "inherit" | "start"
Whether the label is horizontally anchored to the start, middle, or end of its x position.
number
Max width of annotation, including background, for text wrapping.
Default 125
new (cb: ResizeObserverCallback) => ResizeObserver
Optionally inject a ResizeObserver polyfill, else this must be globally available.
boolean
Whether to render a line indicating label text anchor.
Default true
boolean
Whether to render a label background.
Default true
string
Optional subtitle.
number
The vertical offset of the subtitle from the title.
Default 4
ReactText
Optional title font size.
Default 12
ReactText
Optional title font weight.
Default 200
Partial<TextProps>
Optional subtitle Text props (to override color, etc.).
string
Optional title.
ReactText
Optional title font size.
Default 16
ReactText
Optional title font weight.
Default 600
Partial<TextProps>
Optional title Text props (to override color, etc.).
"end" | "middle" | "start"
Whether the label is vertically anchored to the start, middle, or end of its y position.
number
Width of annotation, including background, for text wrapping.
number
Left offset of entire AnnotationLabel, if not specified uses x + dx from Annotation.
number
Top offset of entire AnnotationLabel, if not specified uses y + dy from Annotation.
#<HtmlLabel />
string
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
Optional className to apply to container in addition to 'visx-annotation-label'.
CSSProperties
Optional styles to apply to the HTML container.
"end" | "middle" | "inherit" | "start"
Whether the label is horizontally anchored to the start, middle, or end of its x position.
new (cb: ResizeObserverCallback) => ResizeObserver
Optionally inject a ResizeObserver polyfill, else this must be globally available.
boolean
Whether to render a line indicating label text anchor.
Default true
"end" | "middle" | "start"
Whether the label is vertically anchored to the start, middle, or end of its y position.
number
Left offset of entire AnnotationLabel, if not specified uses x + dx from Annotation.
number
Top offset of entire AnnotationLabel, if not specified uses y + dy from Annotation.