Getting Started

Quick Start

Get up and running in 3 steps:

1. Install

pnpm

pnpm add vue-calendar-activity

npm

npm install vue-calendar-activity

yarn

yarn add vue-calendar-activity

2. Add to your component

<script setup lang="ts">
import { CalendarHeatmap } from 'vue-calendar-activity'
import 'vue-calendar-activity/style.css'

const data = {
  '2024-03-10': 3,
  '2024-05-22': 8,
  '2024-07-04': 5,
  '2024-09-18': 2,
  '2024-11-30': 9,
}
</script>

<template>
  <CalendarHeatmap :data="data" />
</template>

3. Result

Jun

Jul

Aug

Sep

Oct

Nov

Dec

Jan

Feb

Mar

Apr

May

Jun

Mon

Tue

Wed

Thu

Fri

Sat

Sun

TIP

data accepts both an object map { 'YYYY-MM-DD': value } and an array [{ date, value }]. See Data formats below.

---

Installation

pnpm

pnpm add vue-calendar-activity

npm

npm install vue-calendar-activity

yarn

yarn add vue-calendar-activity

Basic usage

Import the component and its styles, then pass your data:

<script setup lang="ts">
import { CalendarHeatmap } from 'vue-calendar-activity'
import 'vue-calendar-activity/style.css'

const data = [
  { date: '2024-06-15', value: 4 },
  { date: '2024-09-20', value: 2 },
  { date: '2024-12-10', value: 7 },
]
</script>

<template>
  <CalendarHeatmap :data="data" start-date="2024-01-01" end-date="2024-12-31" />
</template>

Jan

Feb

Mar

Apr

May

Jun

Jul

Aug

Sep

Oct

Nov

Dec

Mon

Tue

Wed

Thu

Fri

Sat

Sun

Data formats

The component accepts two formats — use whichever fits your backend:

// Array of objects
const data = [
  { date: '2024-01-15', value: 5 },
  { date: '2024-01-16', value: 2 },
]

// Object map  { 'YYYY-MM-DD': value }
const data = {
  '2024-01-15': 5,
  '2024-01-16': 2,
}

Date range

Use range for common presets, or startDate/endDate for full control:

<!-- Last year (default) -->
<CalendarHeatmap :data="data" range="year" />

<!-- Current month only -->
<CalendarHeatmap :data="data" range="month" />

<!-- Custom range -->
<CalendarHeatmap
  :data="data"
  start-date="2023-01-01"
  end-date="2023-12-31"
/>

Listening to events

<script setup lang="ts">
import type { HeatmapDay } from 'vue-calendar-activity'

function onDayClick(day: HeatmapDay, event: MouseEvent) {
  console.log(day.date, day.value)
}
</script>

<template>
  <CalendarHeatmap :data="data" @cell-click="onDayClick" />
</template>