CalendarHeatmap

A GitHub-contribution-graph-style calendar heatmap: each cell is one day, columns are weeks, rows are days of the week. A day with a value shows one of five glyphs (·░▒▓█) by where the value falls in the range from min to max (fitted to the data by default); a value at or below the low end shows as a dim dot, so recorded days stay visible, and days with no entry stay empty.

See also: Heatmap for any 2-D grid of values.

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

CalendarHeatmap(
  start: DateTime(2026, 1, 1),
  end: DateTime(2026, 3, 31),
  values: <DateTime, num>{
    DateTime(2026, 1, 6): 2,
    DateTime(2026, 1, 14): 5,
    DateTime(2026, 1, 21): 8,
    DateTime(2026, 2, 3): 3,
    DateTime(2026, 2, 10): 6,
    DateTime(2026, 2, 18): 9,
    DateTime(2026, 3, 2): 4,
    DateTime(2026, 3, 11): 7,
    DateTime(2026, 3, 20): 1,
  },
)

Details

Months are labeled along the top row at the first week containing each new month. Days are labeled in the left gutter (Mon/Wed/Fri by default — every other row, the typical compact form).

Screen readers and agents get one chart node: semanticLabel plus the date range, the number of days with a value, and the value range the glyphs are scaled to, not a node per day.

Constructors

CalendarHeatmap()

Parameter	Type	Default	Description
values:	Map<DateTime, num>	required	Sparse map of date to value. Days with no entry stay empty; a value at or below the low end of the range renders as the dim dot. Only the date counts, not the time of day, and when several entries fall on the same day, the last one in the map wins.
start:	DateTime	required	First date to include (inclusive).
end:	DateTime	required	Last date to include (inclusive).
min:	num?	—	Low end of the intensity range. null autoscales to values.
max:	num?	—	High end. null autoscales.
color:	Color?	—	Foreground for filled cells. Defaults to the theme’s primary.
cellWidth:	int	2	Cells per day (≥ 1). 1 is the dense GitHub look; 2 reads more clearly at the cost of horizontal space.
weekStartsOn:	CalendarWeekStart	CalendarWeekStart.sunday	Which day starts a week. Defaults to CalendarWeekStart.sunday to match the GitHub contribution graph.
showMonthLabels:	bool	true	Draw month abbreviations along the top row at month boundaries.
showDayLabels:	bool	true	Draw day-of-week labels along the left gutter (Mon/Wed/Fri).
showLegend:	bool	false	When true, append a ·░▒▓█ less – more strip below the grid that shows the glyphs in order from low to high.
semanticLabel:	String	'Calendar heatmap'	Label exposed through the semantic app graph.

Source

CalendarHeatmap is defined in packages/fleury/lib/src/catalog/calendar_heatmap.dart.

Category: Charts & meters · All widgets

Live demo

calendarheatmap_example.dart

Restart Run Expand

Example · editable Revert Format

Widget example() => CalendarHeatmap(
  start: DateTime(2026, 1, 1),
  end: DateTime(2026, 3, 31),
  values: <DateTime, num>{
    DateTime(2026, 1, 6): 2,
    DateTime(2026, 1, 14): 5,
    DateTime(2026, 1, 21): 8,
    DateTime(2026, 2, 3): 3,
    DateTime(2026, 2, 10): 6,
    DateTime(2026, 2, 18): 9,
    DateTime(2026, 3, 2): 4,
    DateTime(2026, 3, 11): 7,
    DateTime(2026, 3, 20): 1,
  },
);

Live preview

Live

ⓘ how this demo runs ⛶ Expand