A GitHub-style contribution heatmap. It lays a year (or any rangeDays) of dated values onto a weeks × weekdays grid, buckets each day's value into a color level, and labels the months and weekdays. Days outside the range are dimmed. It is driven purely by data — there is no card, title, or other scaffolding, so you compose it wherever you need it.

Installation

{
  "registries": {
    "@ikui": "https://ik-ui.pages.dev/r/{name}.json"
  }
}

pnpm dlx shadcn@latest add @ikui/heatmap-calendar

Usage

import { HeatmapCalendar } from "@/components/heatmap-calendar";

const data = [
  { date: "2026-05-01", value: 3 },
  { date: "2026-05-02", value: 7 },
];

<HeatmapCalendar data={data} />;

Each datum is a { date, value } pair; date is a Date or a YYYY-MM-DD string (parsed as a local day). Multiple entries on the same day are summed.

Examples

Custom palette

Pass palette — an array of CSS colors for levels 0..N — to override the default semantic classes. The legend and cells both use it, and the number of colors defines the number of levels.

Legend placement

Configure the legend with an object. It sits below the grid by default; placement="right" moves it to the right instead. You can also set direction, lessText/moreText, or showText.

Custom tooltip

Use renderTooltip to control the content shown on hover. It receives the full HeatmapCell (date, value, level, label).

Compact

Trim the range with rangeDays, shrink cellSize, and turn axisLabels and legend off for a dense inline strip.

Props

LegendConfig

AxisLabelsConfig