# Annotation Chart

1. [Overview](https://developers.google.com/chart/interactive/docs/gallery/annotationchart#Overview)
2. [Example](https://developers.google.com/chart/interactive/docs/gallery/annotationchart#Example)
3. [Loading](https://developers.google.com/chart/interactive/docs/gallery/annotationchart#Loading)
4. [Data Format](https://developers.google.com/chart/interactive/docs/gallery/annotationchart#Data_Format)
5. [Configuration Options](https://developers.google.com/chart/interactive/docs/gallery/annotationchart#Configuration_Options)
6. [Methods](https://developers.google.com/chart/interactive/docs/gallery/annotationchart#Methods)
7. [Events](https://developers.google.com/chart/interactive/docs/gallery/annotationchart#Events)
8. [Data Policy](https://developers.google.com/chart/interactive/docs/gallery/annotationchart#Data_Policy)
9. [Notes](https://developers.google.com/chart/interactive/docs/gallery/annotationchart#notes)

## Overview

Annotation charts are interactive time series line charts that
support annotations. Note that
the [annotated
timeline](https://developers.google.com/chart/interactive/docs/gallery/annotatedtimeline) now automatically uses the Annotation Chart.


**Confusion alert:** Currently, the Google Annotation Chart is
distinct from the
[annotations](https://developers.google.com/chart/interactive/docs/roles)
that other Google charts (currently area, bar, column, combo, line,
and scatter) support. In those charts, the annotations are specified
in a separate datatable column, and displayed as short bits of text
that users can hover over to see the full annotation text. In
contrast, the Annotation Chart displays the full annotations on the
right-hand side, as shown below.

## Example

\<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"\>\</script\> \<div id='chart_div' style='width: 900px; height: 600px;'\>\</div\> google.charts.load('current', {'packages':\['annotationchart'\]}); google.charts.setOnLoadCallback(drawChart); function drawChart() { var data = new google.visualization.DataTable(); data.addColumn('date', 'Date'); data.addColumn('number', 'Kepler-22b mission'); data.addColumn('string', 'Kepler title'); data.addColumn('string', 'Kepler text'); data.addColumn('number', 'Gliese 163 mission'); data.addColumn('string', 'Gliese title'); data.addColumn('string', 'Gliese text'); data.addRows(\[ \[new Date(2314, 2, 15), 12400, undefined, undefined, 10645, undefined, undefined\], \[new Date(2314, 2, 16), 24045, 'Lalibertines', 'First encounter', 12374, undefined, undefined\], \[new Date(2314, 2, 17), 35022, 'Lalibertines', 'They are very tall', 15766, 'Gallantors', 'First Encounter'\], \[new Date(2314, 2, 18), 12284, 'Lalibertines', 'Attack on our crew!', 34334, 'Gallantors', 'Statement of shared principles'\], \[new Date(2314, 2, 19), 8476, 'Lalibertines', 'Heavy casualties', 66467, 'Gallantors', 'Mysteries revealed'\], \[new Date(2314, 2, 20), 0, 'Lalibertines', 'All crew lost', 79463, 'Gallantors', 'Omniscience achieved'\] \]); var chart = new google.visualization.AnnotationChart(document.getElementById('chart_div')); var options = { displayAnnotations: true }; chart.draw(data, options); }

```html
<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type='text/javascript'>
      google.charts.load('current', {'packages':['annotationchart']});
      google.charts.setOnLoadCallback(drawChart);

      function drawChart() {
        var data = new google.visualization.DataTable();
        data.addColumn('date', 'Date');
        data.addColumn('number', 'Kepler-22b mission');
        data.addColumn('string', 'Kepler title');
        data.addColumn('string', 'Kepler text');
        data.addColumn('number', 'Gliese 163 mission');
        data.addColumn('string', 'Gliese title');
        data.addColumn('string', 'Gliese text');
        data.addRows([
          [new Date(2314, 2, 15), 12400, undefined, undefined,
                                  10645, undefined, undefined],
          [new Date(2314, 2, 16), 24045, 'Lalibertines', 'First encounter',
                                  12374, undefined, undefined],
          [new Date(2314, 2, 17), 35022, 'Lalibertines', 'They are very tall',
                                  15766, 'Gallantors', 'First Encounter'],
          [new Date(2314, 2, 18), 12284, 'Lalibertines', 'Attack on our crew!',
                                  34334, 'Gallantors', 'Statement of shared principles'],
          [new Date(2314, 2, 19), 8476, 'Lalibertines', 'Heavy casualties',
                                  66467, 'Gallantors', 'Mysteries revealed'],
          [new Date(2314, 2, 20), 0, 'Lalibertines', 'All crew lost',
                                  79463, 'Gallantors', 'Omniscience achieved']
        ]);

        var chart = new google.visualization.AnnotationChart(document.getElementById('chart_div'));

        var options = {
          displayAnnotations: true
        };

        chart.draw(data, options);
      }
    </script>
  </head>

  <body>
    <div id='chart_div' style='width: 900px; height: 600px;'></div>
  </body>
</html>
```

## Loading


The `google.charts.load` package name is `"annotationchart"`.

```
  google.charts.load("current", {packages: ['annotationchart']});
```


The visualization's class name is `google.visualization.AnnotationChart`.

```
  var visualization = new google.visualization.AnnotationChart(container);
```

## Data Format

You can display one or more lines on your chart. Each row represents an X position
on the chart---that is, a specific time; each line
is described by a set of one to three columns.

- The first column is of type `date` or `datetime`, and specifies the X value of the point on the chart. If this column is of type `date` (and not `datetime`) then the smallest time resolution on the X axis will be one day.
- Each data line is then described by a set of one to three additional columns as described here:
  - Y value - \[*Required, Number*\] The first column in each set describes the value of the line at the corresponding time from the first column. The column label is displayed on the chart as the title of that line.
  - Annotation title - \[*Optional, String* \] If a string column follows the value column, and the `displayAnnotations` option is true, this column holds a short title describing this point. For instance, if this line represents temperature in Brazil, and this point is a very high number, the title could be "Hottest day on record".
  - Annotation text - \[*Optional string* \] If a second string column exists for this series, the cell value will be used as additional descriptive text for this point. You must set the option `displayAnnotations` to true to use this column. You can use HTML tags, if you set `allowHtml` to `true`; there is essentially no size limit, but note that excessively long entries might overflow the display section. You are not required to have this column even if you have an annotation title column for this point. The column label is not used by the chart. For example, if this were the hottest day on record point, you might say something like "Next closest day was 10 degrees cooler!".

## Configuration Options

| Name ||
|---|---|
| allowHtml | If set to true, any annotation text that includes HTML tags will be rendered as HTML. **Type:** boolean **Default:** false |
| allValuesSuffix | A suffix to be added to all values in the legend and tick labels in the vertical axes. **Type:** string **Default:** none |
| annotationsWidth | The width (in percent) of the annotations area, out of the entire chart area. Must be a number in the range 5-80. **Type:** number **Default:** 25 |
| colors | The colors to use for the chart lines and labels. An array of strings. Each element is a string in a valid HTML color format. For example 'red' or '#00cc00'. **Type:** Array of strings **Default:** Default colors |
| dateFormat | The format used to display the date information in the top right corner. The format of this field is as specified by the [java SimpleDateFormat class.](http://icu-project.org/apiref/icu4j/com/ibm/icu/text/SimpleDateFormat.html) **Type:** string **Default:** Either 'MMMM dd, yyyy' or 'HH:mm MMMM dd, yyyy', depending on the type of the first column (date, or datetime, respectively). |
| displayAnnotations | If set to false, the chart will hide the annotations table, and the annotations and annotationText will not be visible (the annotations table will also not be displayed if there are no annotations in your data, regardless of this option). When this option is set to true, after every numeric column, two optional annotation string columns can be added, one for the annotation title and one for the annotation text. **Type:** boolean **Default:** true |
| displayAnnotationsFilter | If set to true, the chart will display a filter control to filter annotations. Use this option when there are many annotations. **Type:** boolean **Default:** false |
| displayDateBarSeparator | Whether to display a small bar separator ( \| ) between the series values and the date in the legend, where true means yes. **Type:** boolean **Default:** true |
| displayExactValues | Whether to display a shortened, rounded version of the values on the top of the graph, to save space; false indicates that it may. For example, if set to false, 56123.45 might be displayed as 56.12k. **Type:** boolean **Default:** false |
| displayLegendDots | Whether to display dots next to the values in the legend text, where true means yes. **Type:** boolean **Default:** true |
| displayLegendValues | Whether to display the highlighted values in the legend, where true means yes. **Type:** boolean **Default:** true |
| displayRangeSelector | Whether to show the zoom range selection area (the area at the bottom of the chart), where false means no. The outline in the zoom selector is a log scale version of the first series in the chart, scaled to fit the height of the zoom selector. **Type:** boolean **Default:** true |
| displayZoomButtons | Whether to show the zoom buttons ("1d 5d 1m" and so on), where false means no. **Type:** boolean **Default:** true |
| fill | A number from 0---100 (inclusive) specifying the alpha of the fill below each line in the line graph. 100 means 100% opaque, and 0 means no fill at all. The fill color is the same color as the line above it. **Type:** number **Default:** 0 |
| legendPosition | Whether to put the colored legend on the same row with the zoom buttons and the date ('sameRow'), or on a new row ('newRow'). **Type:** string **Default:** 'sameRow' |
| max | The maximum value to show on the Y axis. If the maximum data point exceeds this value, this setting will be ignored, and the chart will be adjusted to show the next major tick mark above the maximum data point. This will take precedence over the Y axis maximum determined by `scaleType`. This is similar to `maxValue` in core charts. **Type:** number **Default:** automatic |
| min | The minimum value to show on the Y axis. If the minimum data point is less than this value, this setting will be ignored, and the chart will be adjusted to show the next major tick mark below the minimum data point. This will take precedence over the Y axis minimum determined by `scaleType`. This is similar to `minValue` in core charts. **Type:** number **Default:** automatic |
| numberFormats | Specifies the number format patterns to be used to format the values at the top of the graph. The patterns should be in the format as specified by the [java DecimalFormat class.](http://icu-project.org/apiref/icu4j/com/ibm/icu/text/DecimalFormat.html) - If not specified, the default format pattern is used. - If a single string pattern is specified, it is used for all of the values. - If a map is specified, the keys are (zero-based) indexes of series, and the values are the patterns to be used to format the specified series. You are not required to include a format for every series on the chart; any unspecified series will use the default format. If this option is specified, the `displayExactValues` option is ignored. **Type:** String, or a map of number:String pairs **Default:** automatic |
| scaleColumns | Specifies which values to show on the Y axis tick marks in the graph. The default is to have a single scale on the right side, which applies to both series; but you can have different sides of the graph scaled to different series values. This option takes an array of zero to three numbers specifying the (zero-based) index of the series to use as the scale value. Where these values are shown depends on how many values you include in your array: - If you specify an empty array, the chart will not show Y values next to the tick marks. - If you specify one value, the scale of the indicated series will be displayed on the right side of the chart only. - If you specify two values, a the scale for the second series will be added to the right of the chart. - If you specify three values, a scale for the third series will be added to the middle of the chart. - Any values after the third in the array will be ignored. When displaying more than one scale, it is advisable to set the `scaleType` option to either 'allfixed' or 'allmaximized'. **Type:** Array of numbers **Default:** Automatic |
| scaleFormat | Number format to be used for the axis tick labels. The default of `'#'` displays as an integer. **Type:** string **Default:** '#' |
| scaleType | Sets the maximum and minimum values shown on the Y axis. The following options are available: - 'maximized' - The Y axis will span the minimum to the maximum values of the series. If you have more than one series, use allmaximized. - 'fixed' \[*default* \] - The Y axis varies, depending on the data values values: - If all values are \>=0, the Y axis will span from zero to the maximum data value. - If all values are \<=0, the Y axis will span from zero to the minimum data value. - If values are both positive and negative, the Y axis will range from the series maximum to the series minimum. For multiple series, use 'allfixed'. - 'allmaximized' - Same as 'maximized,' but used when multiple scales are displayed. Both charts will be maximized within the same scale, which means that one will be misrepresented against the Y axis, but hovering over each series will display its true value. - 'allfixed' - Same as 'fixed,' but used when multiple scales are displayed. This setting adjusts each scale to the series to which it applies (use this in conjunction with `scaleColumns`). If you specify the min and/or max options, they will take precedence over the minimum and maximum values determined by your scale type. **Type:** string **Default:** 'fixed' |
| table | Contains options relating to the annotations table. To specify properties of this object, you can use object literal notation: ``` var options: { table: { sortAscending: true, sortColumn: 1 } }; ``` **Type:** object **Default:** null |
| table.sortAscending | If set to `true`, reverses the order of the annotations table and displays them in ascending order. **Type:** boolean **Default:** false |
| table.sortColumn | The column index of the annotations table for which the annotations will be sorted. The index must be either 0, for the annotation label column, or 1, for the annotation text column. **Type:** number **Default:** 0 |
| thickness | A number from 0---10 (inclusive) specifying the thickness of the lines, where 0 is the thinnest. **Type:** number **Default:** 0 |
| zoomEndTime | Sets the end date/time of the selected zoom range. **Type:** Date **Default:** none |
| zoomStartTime | Sets the start date/time of the selected zoom range. **Type:** Date **Default:** none |

## Methods

| Method ||
|---|---|
| `clearChart()` | Clears the chart, and releases all its allocated resources. **Return Type:** none |
| `draw(data, options, state)` | Draws the chart. **Return Type:** none |
| `getContainer()` | Retrieves a handle to the container element containing the annotation chart. **Return Type:** Handle to a DOM element |
| `getSelection()` | Standard `getSelection()` implementation. Selected elements are cell elements. Only one cell can be selected at a time by the user. **Return Type:** Array of selection elements |
| `getVisibleChartRange()` | Returns an object with `start` and `end` properties, which each one of them is a `Date` object, representing the current time selection. **Return Type:** An object with `start` and `end` properties |
| `hideDataColumns(columnIndexes)` | Hides the specified data series from the chart. Accepts one parameter which can be a number or an array of numbers, in which 0 refers to the first data series, and so on. **Return Type:** none |
| `setVisibleChartRange(start, end)` | Sets the visible range (zoom) to the specified range. Accepts two parameters of type `Date` that represent the first and last times of the wanted selected visible range. Set *start* to null to include everything from the earliest date to *end* ; set *end* to null to include everything from *start* to the last date. **Return Type:** none |
| `showDataColumns(columnIndexes)` | Shows the specified data series from the chart, after they were hidden using `hideDataColumns` method. Accepts one parameter which can be a number or an array of numbers, in which 0 refers to the first data series, and so on. **Return Type:** none |

## Events

| Name ||
|---|---|
| `rangechange` | Fired when the user changes the range slider. The new range endpoints will be available as `*event*['start']` and `*event*['end']`: ```javascript google.visualization.events.addListener(chart, 'rangechange', rangechange_handler); function rangechange_handler(e) { console.log('You changed the range to ', e['start'], ' and ', e['end']); } ``` **Properties:** start, end |
| `ready` | The chart is ready for external method calls. If you want to interact with the chart, and call methods after you draw it, you should set up a listener for this event *before* you call the `draw` method, and call them only after the event was fired. **Properties:** none |
| `select` | Fired when the user clicks a visual entity. To learn what has been selected, call [`getSelection()`](https://developers.google.com/chart/interactive/docs/gallery/annotationchart#Methods). **Properties:** none |

## Data Policy


All code and data are processed and rendered in the browser. No data is sent to any server.