Overview
HeatmapGrid displays activity intensity over time in a GitHub-style contribution grid. Great for showing user engagement patterns, submission frequency, or daily activity data.
Features
- GitHub-style contribution grid layout
- Duration presets (3, 6, or 12 months)
- Auto-scrolls to show recent data by default
- Configurable cell sizes (sm, md, lg)
- Multiple color scales (green, blue, purple, orange)
- Optional month and weekday labels
- Tooltips showing date and activity count
- Clickable cells for drill-down
Examples
Cell Sizes
Adjust density with cellSize prop
6 Month Activity
Medium (12px)
JunJulAugSepOctNovDec
MonWedFri
LessMore
Color Scales
Available color scale options
JunJulAugSepOctNovDec
MonWedFri
LessMore
Options
Configuration variations
Compact (no labels)
LessMore
Week starts Monday
JunJulAugSepOctNovDec
MonWedFri
LessMore
Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
data | HeatmapDataPoint[] | required | Array with date and value |
months | 3 | 6 | 12 | 12 | Duration preset (calculates startDate) |
cellSize | "sm" | "md" | "lg" | "md" | Cell size (10px, 12px, 16px) |
scrollToRecent | boolean | true | Auto-scroll to show recent data |
startDate | Date | - | Custom start date (overrides months) |
endDate | Date | today | End date for the grid |
colorScale | "green" | "blue" | "purple" | "orange" | "green" | Color scale for intensity |
weekStartsOn | 0 | 1 | 0 | First day of week (0=Sun, 1=Mon) |
showMonthLabels | boolean | true | Show month labels above grid |
showWeekdayLabels | boolean | true | Show weekday labels on left |
showTooltip | boolean | true | Show tooltip on hover |
onCellClick | function | - | Click handler for cells |
Usage
import { HeatmapGrid, ChartCard } from '@/ui/components/charts';
// Basic heatmap - 6 month view (default scrolls to show recent)
<ChartCard title="Activity" description="Last 6 months">
<HeatmapGrid data={activityData} months={6} />
</ChartCard>
// Duration presets: 3, 6, or 12 months
<HeatmapGrid data={activityData} months={3} /> // Compact 3-month view
<HeatmapGrid data={activityData} months={12} /> // Full year view
// Cell size options: sm (10px), md (12px, default), lg (16px)
<HeatmapGrid data={activityData} months={6} cellSize="lg" />
// Disable auto-scroll (starts at oldest data)
<HeatmapGrid data={activityData} scrollToRecent={false} />
// With custom color scale and options
<HeatmapGrid
data={activityData}
months={6}
colorScale="blue" // green | blue | purple | brand
weekStartsOn={1} // 0 = Sunday, 1 = Monday
/>
// Clickable cells with handler
<HeatmapGrid
data={activityData}
months={6}
onCellClick={(date, value) => {
console.log(`Clicked ${date}: ${value} activities`);
}}
/>