vue3-calendar-heatmap

A lightweight, GitHub-style calendar/activity heatmap component for Vue 3, written in TypeScript. No runtime dependencies besides Vue itself.

Install

npm install @bactv/vue3-calendar-heatmap

Usage

<script setup lang="ts">
import { CalendarHeatmap } from '@bactv/vue3-calendar-heatmap';
import '@bactv/vue3-calendar-heatmap/style.css'; // required — component styles ship as a separate CSS file

const values = [
  { date: '2025-01-03', count: 4 },
  { date: '2025-01-04', count: 0 },
  { date: '2025-01-10', count: 12 },
  // days not present here are treated as "no data"
];
</script>

<template>
  <CalendarHeatmap
    :values="values"
    start-date="2025-01-01"
    end-date="2025-12-31"
    :round="2"
    :dark-mode="false"
    :color="{ mainColor: '#196127' }"
    no-data-text="No activity"
    :tooltip-formatter="(v) => `${v.count} events on ${v.date}`"
  />
</template>

Note: component styles are built as a separate CSS file (dist/calendar-heatmap.css, exposed as vue3-calendar-heatmap-ts/style.css). Always import it once in your app entry point.

Props

| Prop | Type | Default | Description | |---|---|---|---| | values | Array<{ date: Date \| string; count: number; [key: string]: unknown }> | — (required) | Data points. Any day in the range without a matching entry is treated as "no data". | | startDate | string | — (required) | Inclusive start of the rendered range, e.g. '2025-01-01'. | | endDate | string | — (required) | Inclusive end of the rendered range, e.g. '2025-12-31'. | | round | number (0-5) | 0 | Corner rounding of each cell. 0 = square, 5 = full circle (mapped linearly to border-radius). | | darkMode | boolean | false | Uses a built-in dark color scheme when rangeColor isn't provided. | | color | {mainColor: string, mixBase: string} | {mainColor: '#171717'} | Color progression. | | max | number | highest count in values | Upper bound used to distribute rangeColor[2..] across counts. | | noDataText | string \| null | null | Tooltip text for days with no matching entry. null shows no tooltip for those days. | | tooltipFormatter | (value) => string | built-in formatter | Formats the tooltip for days that do have a matching entry. Support plain text and html format | | vertical | boolean | false | Renders weeks as rows instead of columns. |

Emits: day-click — fired with { date, count, data } when a rendered day cell is clicked.

Development

npm install
npm run dev     # playground at src/../playground, exercising all props
npm run build    # builds dist/ (ESM + UMD + .d.ts + css) for publishing

Publishing

npm run build
npm publish

License

MIT