dygraphs Annotations

dygraphs lets you add annotations (markers) to individual points on your chart. These markers have a short bit of text or an icon that's displayed over the chart, plus a longer description that appears when you hover over them.

Demo: Dow Jones Industrial Average

Adding Annotations

There are two methods which are used to add, remove and modify annotations:

Calling dygraph.setAnnotations(dygraph.annotations()) is a no-op: it simply causes the chart to refresh.

Let's say we have a simple chart and wish to add an annotation. Here's how:

<script type="text/javascript">
  g = new Dygraph(
    document.getElementById("graphdiv"),
    "Date,Temperature\n" +
    "2008-05-07,75\n" +
    "2008-05-08,70\n" +
    "2008-05-09,80\n"
  );

  g.ready(function() {
    g.setAnnotations([
    {
      series: "Temperature",
      x: "2008-05-08",
      shortText: "L",
      text: "Coldest Day"
    }
    ]);
  });
</script>

Annotations are JavaScript dictionaries. The series and x fields are required: they indicate which point the annotation should be attached to. If specified, shortText will appear on the annotation "flag". If you don't specify shortText, you can specify icon instead to display a small picture. The text parameter specifies hovertext. If you highlight the annotation and leave the mouse still, it will appear.

If you are using native format, you need to pass in a numeric value for the xval field. For a numeric x-axis, simply pass in the x-value of the data point on which you wish to attach the annotation. For a date axis, pass in Date.parse('YYYY/MM/DD'). This returns milliseconds since epoch for the date. As an alternative, use the x field, see table below.

Modifying Annotations

To remove or modify existing annotations, call the annotations method to get an array of annotations. Modify that array, then pass it back in to setAnnotations. For example, this code deletes the second annotation and changes the series to which the first is attached:

var annotations = g.annotations();
annotations.splice(1,1);  // remove the second annotation
annotations[0].series = "Series 2";
g.setAnnotations(annotations);  // causes a redraw

For a more real-life example, see the annotations demo

Annotations and Data Sources

When you pass a URL as the data source to dygraphs, it must issue a request for the data before drawing the chart. This means that the chart data is not yet available immediately after you call new Dygraph and so the call to g.setAnnotations will fail. The best way around this is to use the ready() method:

g = new Dygraph(div, "path/to/data.csv");
g.ready(function() {
  // This is called when data.csv comes back and the chart draws.
  g.setAnnotations([
    …
  ]);
});

Annotations property reference

These properties can all be set in the dictionary for an annotation. The use of each one is demonstrated on the annotations demo page.

Annotation event handlers

dygraphs lets you attach event handlers to your annotations. These can be specified globally (for all annotations) or on a per-annotation basis:

These event handlers all take the same parameters:

g.updateOptions( {
  annotationClickHandler: function(annotation, point, dygraph, event) {
    // ... access/modify annotation.series, annotation.x, ...
  }
}); 

Again, check out the annotations demo for concrete examples of usage of all these handlers.