
CEO & Co-founder of Visivo
Annotation's Role in BI
How to add text annotations and shaded regions to a Visivo chart, and when each one earns its place.

Why annotations matter
A chart shows what happened. It rarely shows why. The revenue line spikes in December, and every viewer has to work out for themselves whether that was a holiday, a price change or a data problem. An annotation puts the explanation on the chart, next to the point it explains, so the chart carries its own context. Label a trend, mark a milestone, flag an outlier, or shade the window when a change took effect, and the reader does not have to ask.
This matters most for the people who were not in the room when the data was discussed: the executive who reads the dashboard on Monday, or the analyst who joined last month.
How annotations work in Visivo
Visivo supports two kinds of markup on a chart: text annotations and shapes. Both live in a chart's layout, next to the Insights the chart draws, so they are YAML in the project and are reviewed and versioned with everything else.
Adding text annotations
A text annotation places a label at a point on the chart. This project defines a model, an Insight that draws daily revenue from it, and a chart that labels the holiday spike:
name: visivo_project
models:
- name: daily_sales
sql: SELECT sale_date, revenue FROM sales
insights:
- name: daily-revenue
props:
type: scatter
mode: lines
x: ?{ ${ref(daily_sales).sale_date} }
y: ?{ ${ref(daily_sales).revenue} }
charts:
- name: revenue-with-annotation
insights:
- ${ref(daily-revenue)}
layout:
annotations:
- x: "2024-01-01"
y: 500
text: "Sales spike due to holiday season"
showarrow: true
arrowhead: 4
x and y are in data coordinates, so the label sits at January 1 on the x axis and 500 on the y axis. showarrow draws an arrow from the text to that point, and arrowhead picks the arrow style.
Highlighting regions with shapes
A shape marks an area rather than a point: a threshold line, or a shaded window around an event. This chart reuses the same Insight and shades January:
charts:
- name: revenue-with-highlight
insights:
- ${ref(daily-revenue)}
layout:
shapes:
- type: rect
xref: x
yref: paper
x0: "2024-01-01"
x1: "2024-02-01"
y0: 0
y1: 1
fillcolor: "rgba(255,0,0,0.3)"
line:
width: 0
xref: x puts x0 and x1 in data coordinates, so the rectangle runs from January 1 to February 1. yref: paper puts y0 and y1 in plot coordinates, where 0 is the bottom of the plot area and 1 is the top, so the band spans the full height however the y axis scales. The translucent fill and zero-width border keep the data readable through it.
Best practices for annotations
- Keep labels short. A sentence on a chart is clutter. A few words next to the point is a label.
- Place text where it does not cover data. Move the label and let the arrow do the pointing.
- Use contrasting colors, and keep shaded regions translucent so the line stays visible.
- Annotate the few points that matter. If every spike has a label, none of them stands out.
Conclusion
An annotated chart answers the question before anyone asks it. In Visivo, annotations and shapes are a few lines of YAML in a chart's layout, reviewed and versioned with the rest of the project.
The full list of annotation and shape options is in the annotations and shapes documentation. To try it on your own data, get started walks you from install to a first chart.