Annotations
Attach explanatory notes to data, categories, and coordinates.
Annotations are chart-native notes. They attach explanatory text to the chart's data space, so the note can follow its subject when data, filtering, size, theme, or output changes.
Use native labels for repeated values or identities. Use an annotation when one observation, category, slice, or coordinate needs editorial context.
Choose what the note follows
The available anchor depends on the chart type:
| Chart type | Anchor | What it follows |
|---|---|---|
| Column, bar, line, and area | datum | One category and, when present, one series observation |
| Column, bar, line, and area | category | The complete visible shape for one category |
| Column, bar, line, and area | coordinate | One exact category and value position |
| Scatter | datum | One point selected through the chart's id field |
| Scatter | coordinate | One exact X/Y position |
| Pie | datum | One slice selected by category |
Ranged bars and columns do not support annotations. Their start/end interval is already the complete value geometry.
A datum note follows its observation through ordinary data changes. If legend filtering hides that observation, the note hides and returns with it. A category note follows the whole visible category, including a grouped or stacked shape whose size changes when series are hidden. Coordinate notes retain their authored position independently of a particular observation.
When a datum or category no longer exists, the annotation remains authored and produces a warning instead of silently attaching to something else.
Place and connect a note
placement describes the note relative to its subject:
{
"text": "New enterprise contracts",
"anchor": {
"type": "datum",
"category": "Q4",
"series": "Americas"
},
"placement": {
"side": "above",
"align": "center",
"gap": 36
},
"connector": "line"
}Sides are above, right, below, and left. Placement alignment is start, center, or end along that side. The gap is measured in logical pixels. Cartesian and scatter notes default above their subject with centered placement and a 36-pixel gap. Pie notes can leave placement omitted so Szum chooses a side from the visible slice.
connector is none, line, or arrow. Omit it for no connector. Attached notes created in the visual editor start with a line; an exact coordinate starts without one.
The separate top-level align property controls paragraph alignment inside the note box. It does not change which side of the subject the box occupies.
Width and space
Omit width for Auto. Szum measures the text and chooses a readable width within its layout limit. Use a positive number for an exact logical-pixel width. Use "shape" to fit the visible subject when that attachment and placement support it; authoring tools hide that choice when it is unavailable.
Notes reserve layout space by default. Set reserveSpace: false for an intentional overlay, or use { "x": false, "y": true } to reserve one axis only. Reservation is a layout preference rather than a promise that every collision can be avoided. If a reserved note cannot be placed, the chart remains usable and reports a render diagnostic while preserving the annotation.
Annotations do not expand automatic scale domains. An exact coordinate outside the current viewport remains authored but is not drawn.
Appearance and visibility
Notes follow the selected theme's typography and use a theme-colored background plate by default. Customize one note with style:
{
"text": "New enterprise contracts",
"anchor": {
"type": "category",
"category": "Q4"
},
"style": {
"color": "#b43d32",
"fontSize": 16,
"fontWeight": 600,
"background": false
}
}Set visible: false to hide a note without deleting it. Authored colors may use one value for both schemes or separate light and dark values.
Edit annotations visually
In the web editor, open Annotations and choose Add note, then select a datum or category in the chart. Write the note in its inspector. You can also double-click a datum to begin a note directly.
Single-click an existing note to select it, double-click to edit its text, and drag or nudge it to adjust its position. Center keeps the current side and gap while centering the box along that side. Reset position restores centered placement, the default gap, and zero residual offset. Dragging a width handle intentionally changes the note to a fixed width.
The Figma plugin exposes the same authored attachment, text, placement, connector, width, appearance, and visibility decisions. Rebuilding a chart from the plugin uses its stored chart document; manual edits to inserted Figma layers remain ordinary Figma edits.
Every accepted edit updates the chart immediately and participates in undo and redo. Blank text during creation remains temporary and is not stored as a new annotation.
Other patterns
Annotate a pie slice
Combine an exact coordinate with reference lines
See Validation and Review for unresolved-anchor and placement findings, and the Cookbook for every annotation recipe.