Charts

Calendar

A GitHub-style calendar heatmap showing daily values over time.

import { Calendar } from "metricui";

Use Calendar for daily time-series data — commit activity, daily revenue, support tickets, or any metric that varies day-by-day. For aggregated time-series, use AreaChart or HeatMap.

Basic Example

Daily Revenue — 2025

<Calendar
  data={dailyRevenue}
  from="2025-01-01"
  to="2025-12-31"
  title="Daily Revenue — 2025"
  format="currency"
  height={200}
/>

Custom Colors

Pass a colors array to define the sequential color scale. Lower values map to the first color, higher to the last.

Commit Activity

<Calendar
  data={commitData}
  from="2025-01-01"
  to="2025-02-28"
  title="Commit Activity"
  format="number"
  colors={["#d6e685", "#8cc665", "#44a340", "#1e6823"]}
  emptyColor="#161b22"
  height={160}
/>

Vertical Direction

Set direction="vertical" for a top-to-bottom layout. Useful in narrow sidebars or tall panels.

Vertical Calendar

<Calendar
  data={commitData}
  from="2025-01-01"
  to="2025-02-28"
  title="Vertical Calendar"
  direction="vertical"
  format="number"
  height={400}
/>

Props

Prop	Type	Default	Description
`data`	`CalendarDatum[] \| DataRow[]`	—	Nivo CalendarDatum[] ({ day, value }) or flat DataRow[] with dateField/valueField columns.
`dateField`	`string`	`"day"`	Column name for the date when using flat rows.
`valueField`	`string`	`"value"`	Column name for the value when using flat rows.
`from`	`string`	—	Start date (YYYY-MM-DD). Auto-derived from data if omitted.
`to`	`string`	—	End date (YYYY-MM-DD). Auto-derived from data if omitted.
`title`	`string`	—	Chart card title.
`subtitle`	`string`	—	Chart card subtitle.
`description`	`string \| React.ReactNode`	—	Description popover content.
`footnote`	`string`	—	Footnote.
`action`	`React.ReactNode`	—	Action slot.
`height`	`number`	`200`	Chart height in px.
`colors`	`string[]`	—	Sequential color scale for the heatmap cells.
`emptyColor`	`string`	—	Color for days with no data. Default: theme-aware transparent.
`format`	`FormatOption`	—	Value format for tooltips.
`direction`	`"horizontal" \| "vertical"`	`"horizontal"`	Calendar direction.
`animate`	`boolean`	`true`	Enable/disable animation.
`onDayClick`	`(event: CalendarClickEvent) => void`	—	Click handler for a day cell.
`drillDown`	`true \| ((event: CalendarClickEvent) => React.ReactNode)`	—	Drill-down. true = auto table, function = custom content.
`drillDownMode`	`"slide-over" \| "modal"`	`"slide-over"`	Drill-down presentation mode.
`crossFilter`	`boolean \| { field?: string }`	—	Enable cross-filtering. true uses dateField as the field.
`tooltipHint`	`boolean \| string`	—	Tooltip action hint.
`variant`	`CardVariant`	—	Card variant.
`dense`	`boolean`	—	Compact layout.
`className`	`string`	—	Additional CSS class names.
`classNames`	`{ root?: string; header?: string; chart?: string; body?: string; footnote?: string }`	—	Sub-element class name overrides.
`id`	`string`	—	HTML id attribute.
`data-testid`	`string`	—	Test id.
`loading`	`boolean`	—	Loading state.
`empty`	`EmptyState`	—	Empty state configuration.
`error`	`ErrorState`	—	Error state configuration.
`stale`	`StaleState`	—	Stale data indicator.

Data Shape

// Nivo-native format
interface CalendarDatum {
  day: string;   // "YYYY-MM-DD"
  value: number;
}

// Flat-row format (converted via dateField + valueField)
type DataRow = { day: string; value: number; [key: string]: unknown };

Notes

Uses forwardRef.
Date range (from/to) is auto-derived from data if not explicitly set.
Default height is 200px (not 300) since calendar charts are wider than tall.
Color scale is sequential (not categorical) — provide 4-6 gradient stops for best results.
Install @nivo/calendar as a peer dependency.
The aiContext prop (inherited from BaseComponentProps) adds business context for AI Insights analysis. See the AI Insights guide for details.