Skip to content

Vue 3 Calendar Heatmap


A lightweight calendar heatmap Vuejs component built on SVG, inspired by github's contribution calendar graph. With tooltip powered by Tippy.js.

AugSepOctNovDecJanFebMarAprMayJunJulAugTueThuSat
Less
More

Installation

bash
# install in your project
yarn add vue3-cal-heatmap tippy.js
bash
# install in your project
npm install -D vue3-cal-heatmap tippy.js

Import

Global install

typescript
import VueCalendarHeatmap from 'vue3-cal-heatmap'

app.use(VueCalendarHeatmap)

Use specific components

typescript
import { CalendarHeatmap } from 'vue3-cal-heatmap'

app.component('CalendarHeatmap', CalendarHeatmap)

Use directly in component

typescript
import { CalendarHeatmap } from 'vue3-cal-heatmap'

export default {
    components: {
        CalendarHeatmap
    },
    // ...
}

WARNING

A css file is included when importing the package. You may have to setup your bundler to embed the css in your page.

Usage

values

  • Type: Array<{ date: Date | string; count: number; }>

  • Required: true

  • Details:

    Array of objects with date and count keys. date values can be a date parseable string, a millisecond timestamp, or a Date object. count value should be a number.

vue
<calendar-heatmap :values="[{ date: '2018-9-22', count: 6 }]" />

endDate

  • Type: string

  • Required: true

  • Details:

    Can be a date parseable string, a millisecond timestamp, or a Date object. The calendar will start automatically one year before this date.

vue
<calendar-heatmap :end-date="2018-9-22" />

round

  • Type: number between 0 and 5

  • Details:

    Number to create rounded corners or cirlces in heatmap. 0 by default.

vue
<calendar-heatmap :round="0" .../>

Example :round="0"

AugSepOctNovDecJanFebMarAprMayJunJulAugTueThuSat
Less
More

Example :round="5"

AugSepOctNovDecJanFebMarAprMayJunJulAugTueThuSat
Less
More

darkMode

  • Type: boolean

  • Details:

    Boolean to toggle default color range between dark and light mode. Toggle page between light and dark mode to see in action.

vue
<calendar-heatmap dark-mode .../>

Example

AugSepOctNovDecJanFebMarAprMayJunJulAugTueThuSat
Less
More

rangeColor

  • Type: Array<string>

  • Details:

    Array of strings which represents the colors of the progression.

    • The color at rangeColor[0] will always represent the values for a count: null
    • The color at rangeColor[1] will always represent the values for a count: 0
    • The others are automatically distributed over the maximum value of count, unless you specify max props.
vue
<calendar-heatmap :range-color="['#ebedf0', '#9be9a8', '#40c463', '#30a14e', '#216e39']" .../>

TIP

This overwrites the darkModeoption. If you use this option, you have to handle dark mode yourself by using rangeColor.

Example

AugSepOctNovDecJanFebMarAprMayJunJulAugTueThuSat
Less
More

max

  • Type: number

  • Details:

    Any number which should be the max color.

vue
<calendar-heatmap :max="10" .../>

noDataText

  • Type: string

  • Details:

    Tooltip text to display on days without data. null by default (shows no tooltip at all).

vue
<calendar-heatmap :no-data-text="no data for this day" .../>

tooltip

  • Type: boolean

  • Details:

    Boolean for enable/disable tooltip on square hover. true by default.

vue
<calendar-heatmap :tooltip="false" .../>

tooltipUnit

  • Type: string

  • Details:

    String representing heatmap's unit of measure. Value is "contributions" by default.

vue
<calendar-heatmap tooltip-unit="stars" .../>

tooltipFormatter

  • Type: function(value: { date: Date | string; count: number; }): string

  • Details:

    A method to have full control about tooltip content.

vue
<calendar-heatmap :tooltip-formatter="(v) => v.count" .../>