vue-activity-calendar

A lightweight, customizable activity/contribution calendar component for Vue 3 — inspired by GitHub's contribution graph.

Features

• Vue 3 with Composition API & TypeScript
• GitHub-style contribution graph out of the box
• Customizable themes — light, dark, or bring your own colors
• Flexible labels — month names, weekday names, i18n ready
• Tiny bundle — ~2.5 kB gzipped, zero dependencies
• Accessible — native SVG tooltips, keyboard-friendly
• Click events — @block-click with full activity data

Installation

# npm
npm install vue-activity-calendar

# pnpm
pnpm add vue-activity-calendar

# yarn
yarn add vue-activity-calendar

Quick Start

<script setup>
import { ActivityCalendar } from 'vue-activity-calendar'
import 'vue-activity-calendar/style.css'

const data = [
  { date: '2024-01-01', count: 2, level: 1 },
  { date: '2024-01-02', count: 5, level: 2 },
  { date: '2024-01-03', count: 12, level: 4 },
  // ... more data
]
</script>

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

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | Activity[] | required | Array of activity data | | blockSize | number | 12 | Size of each block in pixels | | blockMargin | number | 4 | Margin between blocks | | blockRadius | number | 2 | Border radius of blocks | | colorScheme | 'light' \| 'dark' | 'light' | Color scheme | | fontSize | number | 14 | Font size for labels | | hideColorLegend | boolean | false | Hide the color legend | | hideMonthLabels | boolean | false | Hide month labels | | hideTotalCount | boolean | false | Hide total count text | | labels | Partial<Labels> | — | Custom labels (i18n) | | maxLevel | number | 4 | Maximum activity level | | showWeekdayLabels | boolean | false | Show weekday labels | | theme | CalendarTheme | GitHub theme | Custom color theme | | weekStart | 0-6 | 0 (Sunday) | First day of the week |

Events

| Event | Payload | Description | |-------|---------|-------------| | @block-click | (activity: Activity, event: MouseEvent) | Emitted when a block is clicked |

Data Format

interface Activity {
  date: string   // 'YYYY-MM-DD'
  count: number  // Activity count
  level: 0 | 1 | 2 | 3 | 4  // Intensity level
}

Custom Theme

<template>
  <ActivityCalendar
    :data="data"
    :theme="{
      light: ['#f0f0f0', '#c4edde', '#7ac7c4', '#f73859', '#384259'],
      dark: ['#383838', '#4D455D', '#7DB9B6', '#F5E9CF', '#E96479'],
    }"
  />
</template>

i18n / Custom Labels

<template>
  <ActivityCalendar
    :data="data"
    :labels="{
      months: ['Oca', 'Şub', 'Mar', 'Nis', 'May', 'Haz', 'Tem', 'Ağu', 'Eyl', 'Eki', 'Kas', 'Ara'],
      weekdays: ['Paz', 'Pzt', 'Sal', 'Çar', 'Per', 'Cum', 'Cmt'],
      totalCount: '{{year}} yılında {{count}} aktivite',
      less: 'Az',
      more: 'Çok',
    }"
  />
</template>

Dark Mode

<template>
  <ActivityCalendar :data="data" color-scheme="dark" />
</template>

With Weekday Labels

<template>
  <ActivityCalendar :data="data" show-weekday-labels :week-start="1" />
</template>

Inspiration

This component is the Vue 3 counterpart of react-activity-calendar by @grubersjoe.

License

MIT - Made with ❤️ by Mustafa Vatandas