Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 42 ยท Subplots and Annotations

Annotations, Shapes and Reference Lines

Mark up Plotly charts with text annotations, arrows, lines, rectangles, reference lines and shaded regions, using data coordinates or paper coordinates.

A chart shows data. An annotation tells the reader what to notice: "launch day", "target", "record high", "recession". Plotly has two tools for this. Annotations are pieces of text with an optional arrow. Shapes are lines, rectangles, circles and paths drawn on the chart. Both live in the layout, so they are part of the figure, are exported with it and move with the zoom.

The key idea is the coordinate system. You can anchor a mark to the data (it moves and scales when the user zooms) or to the paper (a fixed place on the chart, from 0 to 1, regardless of zoom).

Text annotations with arrows

fig.add_annotation adds one annotation. The most used options:

  • x, y: the point the annotation refers to, in data coordinates.
  • text: the label. It accepts simple HTML such as <b>, <i> and <br>.
  • showarrow: draw an arrow from the text to the point.
  • ax, ay: where the text sits, as an offset in pixels from the point (the default for axref="pixel").
  • arrowhead, arrowcolor, arrowwidth: the arrow's look.
  • xanchor, yanchor, align: how the text box is aligned to its position.
  • bgcolor, bordercolor, font: the box and its text.
Python Label a peak and a dip

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Annotations are stored in layout.annotations, a tuple. You can change one later with fig.update_annotations(font_size=12) (all of them) or fig.layout.annotations[0].text = "...".

Shapes: lines, rectangles and more

fig.add_shape(type=..., x0, y0, x1, y1, ...) draws a shape. The type is "line", "rect", "circle" or "path" (an SVG path string for arbitrary polygons and curves). Fill and outline are set with fillcolor, opacity and line=dict(color=, width=, dash=). layer="below" places the shape under the traces, which is what you want for shaded backgrounds.

Because horizontal and vertical reference lines are so common, Plotly adds helpers that span the whole plot for you:

Helper Draws
fig.add_hline(y=...) A horizontal line across the plot
fig.add_vline(x=...) A vertical line
fig.add_hrect(y0=, y1=) A horizontal band
fig.add_vrect(x0=, x1=) A vertical band

All four accept annotation_text and annotation_position (such as "top left"), so the label comes with the line.

Python Target line and a shaded period

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Look at the printed yref of the band: y domain. A "domain" reference means "from 0 to 1 of the plot height", so the band always fills the full height however the user zooms. The helper picked the right references for you.

Data coordinates and paper coordinates

Every annotation and shape has xref and yref properties:

  • "x", "y" (or "x2", "y2" for other subplots): data coordinates of that axis.
  • "x domain", "y domain": 0 to 1 across that axis' own plot area.
  • "paper": 0 to 1 across the whole figure area (including margins' inner frame).

Use data coordinates for "this event happened at this x". Use paper or domain coordinates for things that belong to the chart rather than the data: a footnote (xref="paper", yref="paper", x=0, y=-0.2), a watermark, or a source line.

Annotations in data and paper coordinates (Plotly.js)

The footnote stays at the bottom left however you zoom, while the "record" label follows the Q4 bar. The red line mixes both systems: its x-span is paper (edge to edge) but its y-value is in data units.

Annotations in subplots and on other charts

For a figure made with make_subplots, pass row and col to add_annotation, add_shape, add_hline and friends, and Plotly fills in the right axis references. Passing row="all" and col="all" repeats the mark in every cell, which is handy for a shared reference line. Annotations also work on 3D scenes (as scene.annotations) and, in a different form, on pies, where annotations in the middle of a donut is the usual trick for a centre label.

Images and clickable text

Besides text, fig.add_layout_image places a picture (logo, floor plan, satellite tile) at paper or data coordinates, with sizex, sizey, xanchor, opacity and layer. The source can be a URL or a data: URI. A common use is a faint logo at the corner, or a custom background image on which scatter points mark positions.

Annotations may also contain links: text='<a href="https://example.com">source</a>' renders as a clickable link in the browser. You can attach a hovertext to an annotation for more detail, and captureevents=True makes it fire click events (see hover, click and events).

Many annotations get slow and cluttered. If you want a label on every point, use mode="lines+markers+text" and text= on the trace instead. Annotations are for the few things that matter.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which helper draws a shaded vertical band between two x-values?

    add_vrect draws a vertical rectangle spanning the plot height between x0 and x1. add_hrect is its horizontal counterpart.
  2. 2. You want a source note that stays at the bottom-left of the figure when the user zooms. Which references?

    Paper coordinates are fixed fractions of the figure, so they do not move when the axes zoom.
  3. 3. What do ax and ay mean on an annotation with showarrow=True (default axref and ayref)?

    x and y give the target point. ax and ay place the text relative to it in pixels, which also sets the arrow's direction.
  4. 4. Why use layer="below" on a shaded rectangle?

    Shapes default to drawing above the traces. layer="below" keeps backgrounds from covering your data.

Summary

  • add_annotation places text (and arrows); add_shape draws lines, rectangles, circles and paths.
  • add_hline, add_vline, add_hrect and add_vrect are shortcuts with built-in labels.
  • Choose data coordinates for event marks and paper/domain coordinates for chart furniture.
  • row and col target subplots; layer="below" puts shapes behind the data.
  • Keep annotations for the few key points; use trace text for labels on every point.

Next: Facets, Small Multiples and Insets