Blog Help & Support Contact About Login

 Show Nav

Calendar Charts

Overview

A calendar chart or calendar module displays data activity over the course of several months up to a full calendar year. It is useful for comparing data over time (similar to heat maps) or for highlighting specific dates (holidays, birthdays, special events). ZingChart offers numerous set-up options and chart-specific properties to allow for maximum customization. You can specify what year to display, its starting and ending month, and whether your calendar chart's first day of the week is Sunday or Monday. You can also select a color palette, configure your scale, have your calendar chart break across two or more rows, and style cells by weeks, months, and days. We explain how to display a calendar chart with numbered days, as well as how to format and style your tooltips. For more calendar charts, browse our ZingChart Gallery.

Calendar Chart Type

In your chart object, add a "type" attribute and set the value to "calendar". This will display a 12 month calendar chart of the current year.

Note: To adjust the margins of your calendar chart, create a "plotarea" object and use attributes such as "margin-top" and "margin-bottom". Refer to the Plotarea JSON Attributes/Syntax page for margin-related attributes.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Calendar Set-Up

Next, set up your calendar chart. You must specify your calendar year. You can also provide your starting month, ending month, and first day of the week (Sunday or Monday). In the below chart, the year is set to 2000. The calendar starts in March and ends in October, and the first day of the week is set to Monday.

Note: Specifying your calendar year is required. Otherwise your chart will default to display the current year.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "options":{
    "year":{          
      "text":2000,  //Specify your calendar year (required)[1].
      "font-color":"#666699",
      "font-family":"Georgia, serif",
    },
    "start-month":3,//Specify your starting month (1-12)[2].
    "end-month":10, //Specify your ending month (1-12)[3].
    "firstday":"m", //Specify your first day (Sunday ("s") or Monday ("m"))[4].
  }
}

Calendar Year

Create an "options" object. Insert a "year" object, and then a "text" attribute . Specify the calendar year you wish to display. (Without specification, the chart will default to the current year.)

Note: You can style your year's text within the same object, using styling attributes such as "font-color", "font-family", "font-size", "font-weight" ("normal" or "bold"), and "font-style" ("normal" or "italic").

Starting Month

In your "options" object, add a "start-month" attribute. Provide a value between 1-12, with 1 indicating January and 12 indicating December. (Without specification, the calendar will start in January.)

Ending Month

In your "options" object, add an "end-month" attribute. Provide a value between 1-12, with 1 indicating January and 12 indicating December. (Without specification, the calendar will end in December.)

First Day of the Week

In the "options" object, insert a "firstday" attribute. You can set the value to Sunday ("s") or Monday ("m"). (Without specification, Sunday is set as the first day of the week, which is the norm in most North American countries. In most of Europe, however, Monday is considered the first day of the week.)

Values Data

Provide your calendar data. In the "options" object, create a "values" array. Each data element will contain a date with a corresponding value, formatted like this:

"values":[
    ["YYYY-MM-DD", val1],
    ["YYYY-MM-DD", val2],
    ["YYYY-MM-DD", val3],
    ...,
    ["YYYY-MM-DD", valN]
]

Optionally, you can add additional values. Include them as a string in the data element you want them to be associated with. These values aren't automatically visible. (Hover over the April 1st and May 1st values in the below chart. "April Fool's Day!" and "May Flowers!" aren't included in the tooltip.) However, they can be accessed via tokens (%data-info0, %data-info1, etc.). See the Calendar Tooltips section below for further information.

"values":[
    ["YYYY-MM-DD", val1, "info0", "info1", ..., "infoN"],
    ["YYYY-MM-DD", val2, "info0", "info1", ..., "infoN"],
    ["YYYY-MM-DD", val3, "info0", "info1", ..., "infoN"],
    ...,
    ["YYYY-MM-DD", valN, "info0", "info1", ..., "infoN"]
]

With data, a calendar chart now looks like this:

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "options":{
    ...
    "values":[
     ["2016-04-01",50, "April Fool's Day!"],
      ["2016-04-03",-20],
      ["2016-04-07",-10],
      ["2016-04-09",20],
      ["2016-04-13",50],
      ["2016-04-15",-40],
      ["2016-04-16",-5],
      ["2016-04-17",10],
      ["2016-04-28",30],
      ["2016-04-30",-30],
      ["2016-05-01",20, "May Flowers!"],
      ["2016-05-04",-10],
      ["2016-05-06",20],
      ["2016-05-07",30],
      ["2016-05-08",-50],
      ["2016-05-11",40],
      ["2016-05-12",-30],
      ["2016-05-20",-40],
      ["2016-05-22",50],
      ["2016-05-26",-30],
      ["2016-05-28",20],
      ["2016-06-01",30],
      ["2016-06-03",-20],
      ["2016-06-04",-40],
      ["2016-06-09",50]
      ],
  }
}

Calendar-Specific Properties

Once you've set up your calendar and entered your values data, you'll want to customize your chart. Our calendar-specific properties allow you to select a color palette, configure your scale, lay out your rows, create labels for your weekdays and months, and style your cells based on the weekday (1-7), week (1-54), month (1-12), and/or calendar day. All changes in this section are made within your "options" object.

Color Palette

Customize your color palette for displaying negative and positive values on your calendar and scale. In your "options" object, create a "palette" array. Provide two colors (negative and positive, respectively), separated by a comma, as RGB or hexadecimal values.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "options":{
    ...
    "palette":["#FF00FF","#33CC33"],  //Specify your color palette. 
  }
}

Scale

ZingChart does not currently show the calendar scale by default. To display it, add a "scale" object to your "options" object. The scale acts as an indicator, with the pointer position changing as you hover over different cells on the calendar.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "options":{
    ...
    "scale":{   //Insert your scale object to make it visible.
      
    }
  }
}

You can change your scale orientation (horizontal or vertical), style your labels, and customize your pointers using ZingChart shapes. In the below chart, the scale direction was changed to a vertical one, the labels were colored orange, and the pointers were colored blue and changed into three-pointed stars.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "plotarea":{
    "margin-right":100  //Adjust your right margin for vertically-oriented scales.
  },
  "options":{
    ...
    "scale":{
      "direction":"v",                //Scale Direction (horizontal or vertical)[1]
      "label":{                       //Scale Label Styling[2]
        "font-color":"#FF9900",
        "font-family":"Courier New, Courier, monospace",
        "font-size":20,
        "font-weight":"bold",
        "font-style":"italic",
      },
      "pointer":{                     //Scale Pointers[3]
        "type":"star3",
        "background-color":"#0066FF"
      }
    }
  }
}

Scale Orientation

Use the "direction" attribute to change your scale orientation. To display the scale horizontally (the default orientation), provide the "h" value. To display the scale vertically, provide the "v" value.

Note: With the vertically oriented scale, you may need to adjust your margins. Create a "plotarea" object, and add a "margin-right" attribute. Provide a pixel value.

Note: You can also position your scale by adding the "x" and "y" attributes to your "scale" object. Provide a percentage or pixel value.

Scale Labels

Use the "label" object to style your scale labels. You can style the font color, family, size, weight (bold), and style (italic). To specify your font color, add a "font-color" attribute. Provide your color as a hexadecimal or RGB value. To specify your font (or font family), add a "font-family" attribute. Place all of your fonts in a single string, separated by commas. To change your text size, add a "font-size" attribute. Provide a pixel value. Finally, you can bold or italicize your text. For bolding, add a "font-weight" attribute, and set the value to "bold". For italics, add a "font-style" attribute, and set the value to "italic".

Scale Pointers

Use the "pointer" object to set the type and styling for your pointers. Based on ZingChart shapes, you can specify your pointer type with the "type" attribute. Value options include "triangle" (default), "square", "circle", "diamond", "star3", and more. You can style them with attributes such as "background-color" and "size". See our ZingChart Shapes page for more information.

Rows

By default, the calendar chart displays as a single row (1), but you can change the layout so that it displays across 2, 3, 4, 6, or 12 rows. Add a "rows" attribute to your "options" object. Specify your row number.

Note: With different row configurations, you'll need to adjust your chart's height and width in your render method. ZingChart offers flexible layout options so you can size your calendar however you wish.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "options":{
    ...
    "rows":1, //or 2, 3, 4, 6, or 12.
  }
}

Weekday (1-7)

You can format and style your weekday labels, as well as style your weekday rows. In your "options" object, create a "weekday" object. You'll use a "values" array to set your labels, an "item" object to style them, and an "items" object to style your rows. In the below chart, the default weekday labels were replaced with abbreviated days of the week. The labels were then styled to appear orange. The weekday rows for Sunday and Saturday were colored indigo.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "options":{
    ...
    "weekday":{
      "values":["Sun","Mon","Tues","Wed","Thurs","Fri","Sat"],  //Weekday Labels[1]
      "item":{  //Weekday Label Styling[2]
        "font-color":"#FF9900",
        "font-family":"Courier New, Courier, monospace",
        "font-size":20,
        "font-weight":"bold",
        "font-style":"italic"
      },
      "items":{ //Weekday Rows (1-7)[3]
        "wd-1":{
          "background-color":"#666699",
          "alpha":0.8
        },
        "wd-7":{
          "background-color":"#666699",
          "alpha":0.5
        },
      }
    },
  }
}

Weekday Labels

Use the "values" array to set your weekday labels. You can include weekday labels such as the following for a Sunday-starting calendar:

"values":["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"]

Or for a Monday-starting calendar:

"values":["lundi","mardi","mercredi","jeudi","vendredi","samedi","dimanche"]

Label Styling

Use the "item" (singular) object to style your weekday labels.

"weekday":{
    ...
    "item":{
        ...place your styling attributes here...
    }
}

To specify your font color, add a "font-color" attribute. Provide your color as a hexadecimal or RGB value. To specify your font type, add a "font-family" attribute. Place all of your fonts in a single string, separated by commas. To change your text size, add a "font-size" attribute. Provide a pixel value. Finally, you can bold or italicize your text. For bolding, add a "font-weight" attribute, and set the value to "bold". For italics, add a "font-style" attribute, and set the value to "italic".

Weekday Rows

Use the "items" (plural) object to style your weekday rows. Create weekday-specific objects, formatted like so, where you can place your styling attributes. Remember that the weekday starting value is 1, which represents Sunday or Monday, depending on your calendar set-up.

"weekday":{
    "items":{
        "w-N":{     //N can be number 1-7
            ...place your styling attributes here...
        }
    }
}

To specify your background color, add a "background-color" attribute. Provide your color as a hexadecimal or RGB value. To adjust your transparency levels, add an "alpha" attribute. Provide a value between 0 and 1, with 0 being transparent and 1 being opaque. Also, make sure your decimal mark is preceded by a zero.

Week (1-54)

You can style your week columns. In your "options" object, create a "week" object. To style your week columns, add an "items" object. Inside, add week-specific objects, formatted like so, where you can place your styling attributes. Remember that the week starting value is 1, which represents the first week of January.

"week":{
    "items":{
        "w-N":{     //N can be number 1-54
            ...place your styling attributes here...
        }
    }
}

To change a week's background color, add a "background-color" attribute. Provide your color as a hexadecimal or RGB value. To change the color's transparency levels, add an "alpha" attribute. Provide a value between 0 and 1, with 0 being clear and 1 being opaque, and make sure your decimal mark is preceded by a zero. In the below chart, the last two weeks of December were colored orange, with different transparency values.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "options":{
    ...
    "week":{  //Week Columns (1-54)
      "items":{
        "w-52":{
          "background-color":"#FF9900",
          "alpha":0.8
        },
        "w-53":{
          "background-color":"#FF9900",
          "alpha":0.5
        }
      }
    }
  }
}

Month (1-12)

You can format and style your month labels, as well as style your month's cells and borders. In your "options" object, create a "month" object. You'll use a "values" array to set your month labels and an "item" object to style them. You can style your month's cells and borders using an "items" object and/or "outline" object. In the below chart, the default month labels were replaced with fully spelled out months. The labels were then styled to appear blue. The month of December was colored and bordered blue. And the borders for active months (i.e., months with values data) were colored indigo. The remaining month's borders were colored white.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "options":{
    ...
    "month":{
      "values":[null,null,"March","April","May","June","July","August","September","October","November","December"],  //Month Labels[1]
      "item":{  //Label Styling[2]
        "font-color":"#0066FF",
        "font-family":"Courier New, Courier, monospace",
        "font-size":12,
        "font-weight":"bold",
        "font-style":"italic"
      },
      "items":{ //Month Cell Styling[3]
        "m-12":{
          "background-color":"#0066FF",
          "alpha":0.5,
          "outline":{
            "border-color":"#0066FF",
            "border-width":2
          }
        }
      },
      "outline":{ //Month Border Styling[4]
        "border-color":"white",
        "border-width":2,
        "active":{
          "border-color":"#666699",
          "alpha":1,
          "border-width":2
        }
      }
    }
  }
}

Month Labels

To set your month labels, add a "values" array. You can include month labels such as:

"values":["01","02","03","04","05","06","07","08","09","10","11","12"]

When you have a calendar with a non-January starting month, you can also incorporate null values:

"values":[null,null,"March","April","May","June","July","August","September","October","November","December"]

Label Styling

To style your month labels, use the "item" (singular) object.

"month":{
    ...
    "item":{
        ...place your styling attributes here...
    }
}

To specify your font color, add a "font-color" attribute. Provide your color as a hexadecimal or RGB value. To specify your font type, add a "font-family" attribute. Place all of your fonts in a single string, separated by commas. To change your text size, add a "font-size" attribute. Provide a pixel value. Finally, you can bold or italicize your text. For bolding, add a "font-weight" attribute, and set the value to "bold". For italics, add a "font-style" attribute, and set the value to "italic".

Month Cell Styling

To style the background color and border of a particular month, use the "items" (plural) object. Create month-specific objects in the following format, where you can place your styling attributes. Remember that the month starting value is 1, which represents January.

"month":{
    ...
    "items":{
        "m-N":{     //N can be number 1-12
            ...place your cell styling attributes here...
            "outline":{
                ...place your border styling attributes here...
            }
        }
    }
}

For month cell styling, you can use the "background-color" and "alpha" attributes. Provide a color and transparency value (between 0-1), respectively. For the latter, note that 0 indicates transparent and 1 indicates opaque, and make sure to precede your decimal mark with a zero. For border styling, you can use the "border-color" and "border-width" attributes. Provide a color and pixel value, respectively.

Month Border Styling

To style the borders of active and inactive months, use an "outline" object. You can style the borders of your active months (i.e., the months that contain values data) by adding an "active" object, and placing your styling attributes inside it. Border styling attributes placed outside that object will affect all inactive months.

"month":{
    ...
    "outline":{
        ...place your border styling attributes for inactive months here...
        "active":{
            ...place your border styling attributes for active months here...
        }
    }
}

To specify your border color, add a "border-color" attribute. Provide a color value. To specify your border width, add a "border-width" attribute. Provide a pixel value.

Day

You can style day cells individually or apply styles across all inactive (i.e., non-values data and/or individually styled) cells. In your "options" object, create a "day" object.

Individual Day Styling

To style individual calendar days, add an "items" object to your "day" object. Create day-specific objects in the following format, where you can place your styling attributes.

"day":{
    "items":{
        "d-YYYY-MM-DD":{        //YYYY-MM-DD corresponds to year, month, and day
            ...place your styling attributes here...
        }
    }
}

To change a day's background color, add a "background-color" attribute. Provide your color as a hexadecimal or RGB value. To change the color's transparency levels, add an "alpha" attribute. Provide a value between 0 and 1, with 0 being clear and 1 being opaque. Make sure your decimal mark is preceded by a zero.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "options":{
    ...
    "day":{
      "items":{     //To style individual calendar days.
        "d-2015-12-06":{
          "background-color":"red",
          "alpha":1
        },
        "d-2015-12-14":{
          "background-color":"red",
          "alpha":0.5
        },
        "d-2015-12-20":{
          "background-color":"red",
          "alpha":0.8
        },
        "d-2015-12-28":{
          "background-color":"red",
          "alpha":0.3,
        }
      }    
    }
  }
}

Inactive Days Styling

To style your inactive day cells, add an "inactive" object to your "day" object. The styling attributes you provide will apply across all of your calendar cells, with the exception of days containing values data or individualized styling (i.e., styled in the above "items" object).

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "options":{
    ...
    "day":{
      "inactive":{  //To style all inactive (i.e., non-value data or individually styled) cells.
        "background-color":"purple",
        "alpha":0.1,
      },
      "items":{
        "d-2015-12-06":{
          "background-color":"red",
          "alpha":1
        },
        "d-2015-12-14":{
          "background-color":"red",
          "alpha":0.5
        },
        "d-2015-12-20":{
          "background-color":"red",
          "alpha":0.8
        },
        "d-2015-12-28":{
          "background-color":"red",
          "alpha":0.3,
        }
      }    
    }
  }
}

Further Styling and Customization

For further customization, you have the option to create a calendar with numbered days. We also explain how to format and style your tooltips and utilize ZingChart tokens.

Numbered Calendar Days

Calendar days are unnumbered by default. To change this, create a "plot" object, and place a "value-box" object inside it. This will force the calendar days to display. You can style the days with attributes such as "font-color", "font-family", "font-size", and "font-weight" (to change from "bold" to "normal").

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "options":{
    ...
  },
  "plot":{
    "value-box":{   //Numbered Calendar Days
      "font-color":"#666699",
      "font-family":"Georgia, serif",
      "font-size":8,
      "font-weight":"normal"
    }
  },
}

Tooltips

Your calendar's tooltips are what appear when you hover over cells that contain values data. You can format and style your tooltip text, as well as customize the background and borders. To get started, add a "tooltip" object to your chart object.

Text Formatting and Tokens

To customize your tooltip text, add a "text" attribute to your "tooltip" object. Place your desired text inside a string. You can use ZingChart tokens to display information from your values array. Going back to your values data, you provided your data in the following format:

"values":[
    ["YYYY-MM-DD", val1, "info0", "info1", ..., "infoN"],
    ["YYYY-MM-DD", val2, "info0", "info1", ..., "infoN"],
    ...,
    ["YYYY-MM-DD", valN, "info0", "info1", ..., "infoN"]
]

The following tokens correspond accordingly:

Values Data Token
"YYYY-MM-DD" %data-day
val1 %v
"info0" "data-info0
"info1", and so on %data-info1, and so on

See our below chart, where the tooltip text was formatted to display the date (%data-day) with its corresponding value (%v). Hover over the dates for April 1st and May 1st, where text from the optional additional value (%data-info0) displays as well.

Tooltip Styling

You can style your tooltip text, background, and borders using the styling attributes discussed throughout this document. They include "font-color", "font-family", "font-size", "font-weight", and "font-style" for your text. Customize your background with the "background-color" and "alpha" attributes. And customize your borders with the "border-color" and "border-width" attributes. In the below chart, the tooltips were styled so that the text and borders appear indigo and the background appears white.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart
{
  "type":"calendar",
  "options":{
    ...
  },
  "tooltip":{   //Tooltips
    "text":"%data-day: %v <br><br> %data-info0",
    "font-color":"#666699",
    "font-family":"Georgia",
    "font-size":12,
    "font-weight":"normal", //or "bold"
    "font-style":"normal", //or "italic"
    "background-color":"white",
    "alpha":0.8,
    "border-color":"#666699",
    "border-width":1,
  }
}

Summary

Got a question about how calendar charts work? We are happy to help. Email support@zingchart.com or start a chat right here on this page for help.