Google Charts

Calendar Chart beta


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 or VML, 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.google.com/jsapi"></script>
    <script type="text/javascript">
      google.load("visualization", "1.1", {packages:["calendar"]});
      google.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 sankey 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.load package name is "calendar":

  google.load("visualization", "1", {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
Purpose: Dates Values
Data Type: date, datetime, or timeofday number
Role: domain data

 

Configuration Options

Name Type Default Description
calendar.cellColor object { stroke: '#fff', strokeOpacity: 1, strokeWidth: 1 } 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.
        }
      }
    };
    
calendar.cellSize integer 16 The size of the calendar day squares:
    var options = { calendar: { cellSize: 10 } };
    
calendar.dayOfWeekLabel object { fontName: 'sans-serif', color: '#888', bold: false, italic: false } 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
        }
      }
    };
    
calendar.dayOfWeekRightSpace integer 4 The distance between the right edge of the week labels and the left edge of the chart day squares.
calendar.daysOfWeek string 'SMTWTFS' The single-letter labels to use for Sunday through Saturday.
calendar.focusedCellColor object { stroke: '#000', strokeOpacity: 1, strokeWidth: 2 } 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
        }
      }
    };
    
calendar.monthLabel object { fontName: 'sans-serif', color: '#888', bold: false, italic: false } Style for the month labels, e.g.:
    var options = {
      calendar: {
        monthLabel: {
          fontName: 'Times-Roman',
          fontSize: 16,
          color: 'green',
          bold: true,
          italic: false
        }
      }
    };
    
calendar.monthOutlineColor object { stroke: '#000', strokeOpacity: 1, strokeWidth: 1 } 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.)
calendar.underMonthSpace integer 6 The number of pixels between the bottom of the month labels and the top of the day squares:
    var options = { calendar: { underMonthSpace: 12 } };
    
calendar.underYearSpace integer 0 The number of pixels between the bottom-most year label and the bottom of the chart:
    var options = { calendar: { underYearSpace: 2 } };
    
calendar.unusedMonthOutlineColor object { stroke: '#c9c9c9', strokeOpacity: 1, strokeWidth: 1 } 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.)
forceIFrame boolean false Draws the chart inside an inline frame. (Note that on IE8, this option is ignored; all IE8 charts are drawn in i-frames.)
height number height of the containing element Height of the chart, in pixels.
noDataPattern object null 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'
         }
    
width number width of the containing element Width of the chart, in pixels.

Methods

Method Return Type Description
draw(data, options) none Draws the chart. The chart accepts further method calls only after the ready event is fired. Extended description.
getBoundingBox(id) Object

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), 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.

getSelection() Array of selection elements Returns an array of the selected chart entities. Selectable entities are bars, legend entries and categories. A bar correlates 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.
setSelection() none Selects the specified chart entities. Cancels any previous selection. Selectable entities are bars, legend entries and categories. A bar correlates 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.
clearChart() none Clears the chart, and releases all of its allocated resources.

Events

Name Description Properties
error Fired when an error occurs when attempting to render the chart. id, message
onmouseover Fired when the user mouses over a visual entity. Passes back the row and column indices of the corresponding data table element. A bar correlates 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). row, column
onmouseout Fired when the user mouses away from a visual entity. Passes back the row and column indices of the corresponding data table element. A bar correlates 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). row, column
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. None
select Fired when the user clicks a visual entity. To learn what has been selected, call getSelection(). None

Data Policy

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

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.