Contribution Graph
A GitHub-style calendar heatmap for visualizing daily activity over a year.
The ContributionGraph component requires Vue and Tailwind CSS and inherits Nuxt UI colors when available. It plots a value per day across a year as a calendar heatmap — the familiar GitHub "contributions" grid. Use it for commit activity, usage density, streaks, publishing cadence or any per-day metric where the pattern over time matters more than exact values.
Example
Each column is a week, each cell a day; color intensity scales with the day's count. Hover a cell for its value.
<script setup lang="ts">
// Sparse list of { date, count }. Missing days render as empty (level 0).
const data = [
{ date: '2025-01-06', count: 3 },
{ date: '2025-01-07', count: 8 },
{ date: '2025-01-09', count: 1 }
// ...one entry per active day across the year
]
</script>
<template>
<ContributionGraph
:data="data"
color="var(--ui-success)"
/>
</template>
nuxt-charts add ContributionGraph
Data
Pass a sparse array of { date, count } objects. Dates use the YYYY-MM-DD format and only active days need an entry — any day without one is rendered as the empty (level 0) state. The grid starts on the Sunday of the earliest date's week so every column is a full seven-day week.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
data | { date: string, count: number }[] | Required | Sparse list of day → count. Missing days are treated as 0. |
levels | number | 4 | Number of intensity buckets (excluding the empty state). |
color | string | var(--ui-primary) | Base color for the highest intensity; lower levels fade from it. |
cellSize | number | 12 | Size of each day cell in pixels. |
cellGap | number | 3 | Gap between cells in pixels. |
cellRadius | number | 2 | Corner radius of each cell in pixels. |
showWeekdayLabels | boolean | true | Show the Mon / Wed / Fri labels column. |
showMonthLabels | boolean | true | Show the month labels row. |
showLegend | boolean | true | Show the Less → More legend. |
maxCount | number | data max | Explicit upper bound for the color scale. |
tooltipFormatter | (day) => string | — | Custom tooltip text for a day. |
startDate / endDate | string | Data bounds | Explicit YYYY-MM-DD bounds; use these to show inactive periods. |
locale | string | 'en-US' | Locale for month names, weekday labels, and tooltip dates. |
label | string | 'Daily activity' | Accessible name for the chart. |
lessLabel / moreLabel | string | 'Less' / 'More' | Legend text. |
emptyColor | string | Nuxt UI elevated background, then Tailwind gray | Color for inactive cells. |
showTooltip | boolean | true | Show native SVG tooltips. |
Date calculations use UTC so cells stay aligned in every timezone. Empty data displays no cells unless explicit bounds are supplied. Colors accept CSS variables; Tailwind color variables provide defaults when Nuxt UI is absent.