CalendarHeatmap class

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.

CalendarHeatmap(
  start: DateTime(2024, 1, 1),
  end:   DateTime(2024, 12, 31),
  values: {
    DateTime(2024, 3, 15): 4,
    DateTime(2024, 3, 16): 2,
    // ...
  },
)

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.

Inheritance
Available extensions

Constructors

CalendarHeatmap({Key? key, required Map<DateTime, num> values, required DateTime start, required DateTime end, num? min, num? max, Color? color, int cellWidth = 2, CalendarWeekStart weekStartsOn = CalendarWeekStart.sunday, bool showMonthLabels = true, bool showDayLabels = true, bool showLegend = false, String semanticLabel = 'Calendar heatmap'})
const

Properties

cellWidth → int
Cells per day (≥ 1). 1 is the dense GitHub look; 2 reads more clearly at the cost of horizontal space.
final
color → Color?
Foreground for filled cells. Defaults to the theme's primary.
final
end → DateTime
Last date to include (inclusive).
final
hashCode → int
The hash code for this object.
no setterinherited
key → Key?
finalinherited
max → num?
High end. null autoscales.
final
min → num?
Low end of the intensity range. null autoscales to values.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
semanticLabel → String
Label exposed through the semantic app graph.
final
showDayLabels → bool
Draw day-of-week labels along the left gutter (Mon/Wed/Fri).
final
showLegend → bool
When true, append a ·░▒▓█ less – more strip below the grid that shows the glyphs in order from low to high.
final
showMonthLabels → bool
Draw month abbreviations along the top row at month boundaries.
final
start → DateTime
First date to include (inclusive).
final
values → Map<DateTime, num>
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.
final
weekStartsOn → CalendarWeekStart
Which day starts a week. Defaults to CalendarWeekStart.sunday to match the GitHub contribution graph.
final

Methods

animate({Duration? duration, Curve? curve, Object? trigger, bool repeat = false}) → Animate

Available on Widget, provided by the AnimateExtension extension

Starts an Animate chain over this widget. duration / curve apply to the whole chain. With no trigger it plays on mount; with a non-null trigger it rests on mount and replays whenever the token changes.
build(BuildContext context) → Widget
Describes the part of the user interface represented by this widget.
override
createElement() → StatelessElement
Creates the Element that will mount this widget into the tree.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited