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.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: | None |
None |
... |
Configuration Options
Name | |
---|---|
calendar.cellColor |
The 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 } } }; 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 } } }; 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: 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 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 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 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: '#76a7fa', color: '#a0c3ff' } Type: object
Default: null
|
tooltip.isHtml |
Set to Note: customization of the HTML tooltip content via the tooltip column data role is not supported by the Pie Chart and Bubble Chart 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
Return Type: none
|
getBoundingBox(id) |
Returns an object containing the left, top, width, and height of chart element
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.
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.
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 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 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 Properties: none
|
select |
Fired when the user clicks a visual entity. To learn what has been selected, call
Properties: none
|
Data Policy
All code and data are processed and rendered in the browser. No data is sent to any server.