# Calendar Chart

1. [Overview](https://developers.google.com/chart/interactive/docs/gallery/calendar#Overview)
2. [A Simple Example](https://developers.google.com/chart/interactive/docs/gallery/calendar#SimpleExample)
3. [Days](https://developers.google.com/chart/interactive/docs/gallery/calendar#Days)
4. [Weeks](https://developers.google.com/chart/interactive/docs/gallery/calendar#Weeks)
5. [Months](https://developers.google.com/chart/interactive/docs/gallery/calendar#Months)
6. [Years](https://developers.google.com/chart/interactive/docs/gallery/calendar#Years)
7. [Loading](https://developers.google.com/chart/interactive/docs/gallery/calendar#Loading)
8. [Data Format](https://developers.google.com/chart/interactive/docs/gallery/calendar#Data_Format)
9. [Configuration Options](https://developers.google.com/chart/interactive/docs/gallery/calendar#Configuration_Options)
10. [Methods](https://developers.google.com/chart/interactive/docs/gallery/calendar#Methods)
11. [Events](https://developers.google.com/chart/interactive/docs/gallery/calendar#Events)
12. [Data Policy](https://developers.google.com/chart/interactive/docs/gallery/calendar#Data_Policy)

## Overview


**Note:** JavaScript counts months starting at **zero**: January is 0, February is 1, and
December is 11. If your calendar chart seems off by a month, this is why.


A *calendar chart* is a visualization used to show activity over the course of a long span
of time, such as months or years. They're best used when you want to illustrate how some quantity
varies depending on the day of the week, or how it trends over time.


The calendar chart may be undergoing substantial revisions in future Google Charts releases.


Calendar charts are rendered in the browser using
[SVG](http://www.w3.org/Graphics/SVG/) or
[VML](http://en.wikipedia.org/wiki/Vector_Markup_Language), whichever is appropriate
for the user's browser. Like all Google charts, calendar charts display tooltips when the user
hovers over the data. And credit where credit is due: our calendar chart was inspired by the D3
calendar visualization.

## A Simple Example


Let's say we wanted to display how the attendance for a sports team varied throughout the season.
With a calendar chart, we can use brightness to indicate the values and let people see trends at
a glance:

You can mouse over the individual days to see the underlying data values.


To create a calendar chart, load the `calendar` package and then create two columns,
one for the dates and one for the values. (An optional third column for customized styling is
coming in a future Google Charts release.)

Then fill in your rows with date-value pairs, as shown below.

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

   function drawChart() {
       var dataTable = new google.visualization.DataTable();
       dataTable.addColumn({ type: 'date', id: 'Date' });
       dataTable.addColumn({ type: 'number', id: 'Won/Loss' });
       dataTable.addRows([
          [ new Date(2012, 3, 13), 37032 ],
          [ new Date(2012, 3, 14), 38024 ],
          [ new Date(2012, 3, 15), 38024 ],
          [ new Date(2012, 3, 16), 38108 ],
          [ new Date(2012, 3, 17), 38229 ],
          // Many rows omitted for brevity.
          [ new Date(2013, 9, 4), 38177 ],
          [ new Date(2013, 9, 5), 38705 ],
          [ new Date(2013, 9, 12), 38210 ],
          [ new Date(2013, 9, 13), 38029 ],
          [ new Date(2013, 9, 19), 38823 ],
          [ new Date(2013, 9, 23), 38345 ],
          [ new Date(2013, 9, 24), 38436 ],
          [ new Date(2013, 9, 30), 38447 ]
        ]);

       var chart = new google.visualization.Calendar(document.getElementById('calendar_basic'));

       var options = {
         title: "Red Sox Attendance",
         height: 350,
       };

       chart.draw(dataTable, options);
   }
    </script>
  </head>
  <body>
    <div id="calendar_basic" style="width: 1000px; height: 350px;"></div>
  </body>
</html>
```

## Days


Each square in a calendar chart represents a day. Currently, the color of the data cells can't be
customized, although that will change in the next release of Google Charts.


If the data values are all positive, the colors will range from white to blue, with the deepest
blues indicating the highest values. If there are negative data values, they will appear orange,
as shown below.

The code for this calendar is similar to the first, except that the rows look like this:

```
          [ new Date(2013, 9, 4), 10 ],
          [ new Date(2013, 9, 5), 3 ],
          [ new Date(2013, 9, 7), -1 ],
          [ new Date(2013, 9, 8), 2 ],
          [ new Date(2013, 9, 12), -1 ],
          [ new Date(2013, 9, 13), 1 ],
          [ new Date(2013, 9, 15), 1 ],
          [ new Date(2013, 9, 16), -4 ],
```

You can change the size of the days ("cells") with the `calendar.cellSize` option:


Here, we changed `calendar.cellSize` to 10, shrinking the days and therefore the chart
as a whole.

```
       var options = {
         title: 'Red Sox Attendance',
         calendar: { cellSize: 10 },
       };
```

Days with no data values can be customized with the `noDataPattern` option:


Here, we set the `color` to a light blue and `backgroundColor` to a
slightly darker shade:

```
       var options = {
         title: "Red Sox Attendance",
         height: 350,
         noDataPattern: {
           backgroundColor: '#76a7fa',
           color: '#a0c3ff'
         }
       };
```


You can control the cell border color, border width, and opacity with
`calendar.cellColor`:


You'll need to be careful to choose a stroke color that will be distinguished from the
`monthOutlineColor`, or to choose a low opacity. Here are the options for the chart
above:

```
  var options = {
    title: 'Red Sox Attendance',
    height: 350,
    calendar: {
      cellColor: {
        stroke: '#76a7fa',
        strokeOpacity: 0.5,
        strokeWidth: 1,
      }
    }
  };
```


If you focus on a day in the above chart, the border will highlight in red. You can control that
behavior with the `calendar.focusedCellColor` options:

```
  var options = {
    title: 'Red Sox Attendance',
    height: 350,
    calendar: {
      focusedCellColor: {
        stroke: '#d3362d',
        strokeOpacity: 1,
        strokeWidth: 1,
      }
    }
  };
```

## Weeks


By default, the days of the week are labeled with the first letters of Sunday through Saturday.
You can't change the ordering of the days, but you can change what letters are used with
the `calendar.daysOfWeek` option. Also, you can control the padding between the days of
the week and the chart with `calendar.dayOfWeekRightSpace`, and you can customize
the text style with `calendar.dayOfWeekLabel`:


Here, we change the font of the week labels, put in a padding of 10 pixels between the labels and
the chart data, and start weeks on Monday.

```
  var options = {
    title: 'Red Sox Attendance',
    height: 350,
    calendar: {
      dayOfWeekLabel: {
        fontName: 'Times-Roman',
        fontSize: 12,
        color: '#1a8763',
        bold: true,
        italic: true,
      },
      dayOfWeekRightSpace: 10,
      daysOfWeek: 'DLMMJVS',
    }
  };
```

## Months


By default, months are identified by dark grey lines. You can use the
`calendar.monthOutlineColor` option to control the borders, the
`calendar.monthLabel` to customize the label font, and
`calendar.underMonthSpace` to adjust the label padding:


We set the label font to a deep red 12pt Times-Roman bold italic, set the outlines to the same
color, and put in a padding of 16 pixels. The unused month outlines are set to a fainter color of
the same hue.

```
  var options = {
    title: 'Red Sox Attendance',
    height: 350,
    calendar: {
      monthLabel: {
        fontName: 'Times-Roman',
        fontSize: 12,
        color: '#981b48',
        bold: true,
        italic: true
      },
      monthOutlineColor: {
        stroke: '#981b48',
        strokeOpacity: 0.8,
        strokeWidth: 2
      },
      unusedMonthOutlineColor: {
        stroke: '#bc5679',
        strokeOpacity: 0.8,
        strokeWidth: 1
      },
      underMonthSpace: 16,
    }
  };
```

## Years


The years in calendar charts are always on the left edge of the chart, and can be customized with
`calendar.yearLabel` and `calendar.underYearSpace`:


We set the year font to a dark green 32pt Times-Roman bold italic, and add ten pixels between the
year labels and the bottom of the chart:

```
  var options = {
    title: 'Red Sox Attendance',
    height: 350,
    calendar: {
      underYearSpace: 10, // Bottom padding for the year labels.
      yearLabel: {
        fontName: 'Times-Roman',
        fontSize: 32,
        color: '#1A8763',
        bold: true,
        italic: true
      }
    }
  };
```

## Loading


The `google.charts.load` package name is `"calendar"`:

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


The visualization's class name is `google.visualization.Calendar`:

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

## Data Format

**Rows:** Each row in the table represents a date.

**Columns:**

|   | Column 0 | Column 1 | ... | Column *N* (optional) |
| Purpose: | Dates | Values | ... | Optional roles |
| Data Type: | date, datetime, or timeofday | number | ... |   |
| Role: | domain | data | ... |   |
| Optional [column roles](https://developers.google.com/chart/interactive/docs/roles): | *None* | *None* | ... | - [tooltip](https://developers.google.com/chart/interactive/docs/roles#tooltiprole) |
|---|---|---|---|---|

## Configuration Options

| Name ||
|---|---|
| calendar.cellColor | The `calendar.cellColor` option lets you customize the border of the calendar day squares: ``` var options = { calendar: { cellColor: { stroke: 'red',      // Color the border of the squares. strokeOpacity: 0.5, // Make the borders half transparent. strokeWidth: 2      // ...and two pixels thick. } } }; ``` **Type:** object **Default:** `{ stroke: '#fff', strokeOpacity: 1, strokeWidth: 1 }` |
| calendar.cellSize | The size of the calendar day squares: ``` var options = { calendar: { cellSize: 10 } }; ``` **Type:** integer **Default:** 16 |
| calendar.dayOfWeekLabel | Controls the font style of the week labels at the top of the chart: ``` var options = { calendar: { dayOfWeekLabel: { fontName: 'Times-Roman', fontSize: 12, color: 'black', bold: false, italic: false } } }; ``` **Type:** object **Default:** `{ fontName: 'sans-serif', color: '#888', bold: false, italic: false }` |
| calendar.dayOfWeekRightSpace | The distance between the right edge of the week labels and the left edge of the chart day squares. **Type:** integer **Default:** 4 |
| calendar.daysOfWeek | The single-letter labels to use for Sunday through Saturday. **Type:** string **Default:** `'SMTWTFS'` |
| calendar.focusedCellColor | When the user focuses (say, by hovering) over a day square, calendar charts will highlight the square. ``` var options = { calendar: focusedCellColor: { stroke: 'red', strokeOpacity: 0.8, strokeWidth: 3 } } }; ``` **Type:** object **Default:** `{ stroke: '#000', strokeOpacity: 1, strokeWidth: 2 }` |
| calendar.monthLabel | Style for the month labels, e.g.: ``` var options = { calendar: { monthLabel: { fontName: 'Times-Roman', fontSize: 16, color: 'green', bold: true, italic: false } } }; ``` **Type:** object **Default:** `{ fontName: 'sans-serif', color: '#888', bold: false, italic: false }` |
| calendar.monthOutlineColor | Months with data values are delineated from others using a border in this style. ``` var options = { calendar: { monthOutlineColor: { stroke: 'blue', strokeOpacity: 0.8, strokeWidth: 2 } } }; ``` (Also see `calendar.unusedMonthOutlineColor`.) **Type:** object **Default:** `{ stroke: '#000', strokeOpacity: 1, strokeWidth: 1 }` |
| calendar.underMonthSpace | The number of pixels between the bottom of the month labels and the top of the day squares: ``` var options = { calendar: { underMonthSpace: 12 } }; ``` **Type:** integer **Default:** 6 |
| calendar.underYearSpace | The number of pixels between the bottom-most year label and the bottom of the chart: ``` var options = { calendar: { underYearSpace: 2 } }; ``` **Type:** integer **Default:** 0 |
| calendar.unusedMonthOutlineColor | Months *without* data values are delineated from others using a border in this style. ``` var options = { calendar: { unusedMonthOutlineColor: { stroke: 'yellow', strokeOpacity: 0.8, strokeWidth: 2 } } }; ``` (Also see `calendar.monthOutlineColor`.) **Type:** object **Default:** `{ stroke: '#c9c9c9', strokeOpacity: 1, strokeWidth: 1 }` |
| colorAxis | An object that specifies a mapping between color column values and colors or a gradient scale. To specify properties of this object, you can use object literal notation, as shown here: ``` {minValue: 0,  colors: ['#FF0000', '#00FF00']} ``` **Type:** object **Default:** null |
| colorAxis.colors | Colors to assign to values in the visualization. An array of strings, where each element is an HTML color string, for example: `colorAxis: {colors:['red','#004411']}`. You must have at least two values; the gradient will include all your values, plus calculated intermediary values, with the first color as the smallest value, and the last color as the highest. **Type:** array of color strings **Default:** null |
| colorAxis.maxValue | If present, specifies a maximum value for chart color data. Color data values of this value and higher will be rendered as the last color in the `colorAxis.colors` range. **Type:** number **Default:** Maximum value of color column in chart data |
| colorAxis.minValue | If present, specifies a minimum value for chart color data. Color data values of this value and lower will be rendered as the first color in the `colorAxis.colors` range. **Type:** number **Default:** Minimum value of color column in chart data |
| colorAxis.values | If present, controls how values are associated with colors. Each value is associated with the corresponding color in the `colorAxis.colors` array. These values apply to the chart color data. Coloring is done according to a gradient of the values specified here. Not specifying a value for this option is equivalent to specifying \[minValue, maxValue\]. **Type:** array of numbers **Default:** null |
| forceIFrame | Draws the chart inside an inline frame. (Note that on IE8, this option is ignored; all IE8 charts are drawn in i-frames.) **Type:** boolean **Default:** false |
| height | Height of the chart, in pixels. **Type:** number **Default:** height of the containing element |
| noDataPattern | Calendar charts use a striped diagonal pattern to indicate that there is no data for a particular day. Use the `noDataPattern.backgroundColor` and `noDataPattern.color` options to override the grayscale defaults, e.g.: ``` noDataPattern: { backgroundColor: '#76a7fa', color: '#a0c3ff' } ``` **Type:** object **Default:** null |
| tooltip.isHtml | Set to `false` to use SVG-rendered (rather than HTML-rendered) tooltips. See [Customizing Tooltip Content](https://developers.google.com/chart/interactive/docs/customizing_tooltip_content) for more details. **Note:** customization of the HTML tooltip content via the [tooltip column data role](https://developers.google.com/chart/interactive/docs/roles#tooltiprole) is **not** supported by the [Pie Chart](https://developers.google.com/chart/interactive/docs/gallery/piechart) and [Bubble Chart](https://developers.google.com/chart/interactive/docs/gallery/bubblechart) visualizations. **Type:** boolean **Default:** true |
| width | Width of the chart, in pixels. **Type:** number **Default:** width of the containing element |

## Methods

| Method ||
|---|---|
| `draw(data, options)` | Draws the chart. The chart accepts further method calls only after the [`ready`](https://developers.google.com/chart/interactive/docs/gallery/calendar#Events)event is fired. [`Extended description`](https://developers.google.com/chart/interactive/docs/reference#visdraw). **Return Type:** none |
| `getBoundingBox(id)` | Returns an object containing the left, top, width, and height of chart element `id`. The format for `id` isn't yet documented (they're the return values of [event handlers](https://developers.google.com/chart/interactive/docs/events)), but here are some examples: > `var cli = chart.getChartLayoutInterface();` > Height of the chart area > :   `cli.getBoundingBox('chartarea').height` > Width of the third bar in the first series of a bar or column chart > :   `cli.getBoundingBox('bar#0#2').width` > Bounding box of the fifth wedge of a pie chart > :   `cli.getBoundingBox('slice#4')` > Bounding box of the chart data of a vertical (e.g., column) chart: > :   `cli.getBoundingBox('vAxis#0#gridline')` > Bounding box of the chart data of a horizontal (e.g., bar) chart: > :   `cli.getBoundingBox('hAxis#0#gridline')` Values are relative to the container of the chart. Call this *after* the chart is drawn. **Return Type:** object |
| `getSelection()` | Returns an array of the selected chart entities. Selectable entities are bars, legend entries and categories. A bar corresponds to a cell in the data table, a legend entry to a column (row index is null), and a category to a row (column index is null). For this chart, only one entity can be selected at any given moment. [`Extended description`](https://developers.google.com/chart/interactive/docs/reference#visgetselection). **Return Type:** Array of selection elements |
| `setSelection()` | Selects the specified chart entities. Cancels any previous selection. Selectable entities are bars, legend entries and categories. A bar corresponds to a cell in the data table, a legend entry to a column (row index is null), and a category to a row (column index is null). For this chart, only one entity can be selected at a time. [`Extended description`](https://developers.google.com/chart/interactive/docs/reference#vissetselection). **Return Type:** none |
| `clearChart()` | Clears the chart, and releases all of its allocated resources. **Return Type:** none |

## Events

| Name ||
|---|---|
| `error` | Fired when an error occurs when attempting to render the chart. **Properties:** id, message |
| `onmouseover` | Fired when the user mouses over a visual entity. Passes back the row index and date value of the entity. If there is no data table element for the entity, the value returned for the row index is `undefined`. **Properties:** row, date |
| `onmouseout` | Fired when the user mouses away from a visual entity. Passes back the row index and date value of the entity. If there is no data table element for the entity, the value returned for the row index is `undefined`. **Properties** row, date |
| `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/calendar#Methods). **Properties:** none |

## Data Policy


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