Skip to main content
196

Search Lumen

Find components, APIs, guides, and recipes.

GitHub
Web docs
Data display

CalendarHeatmap

Shows daily patterns with explicit missing observations.

FrameworksAstro · React · Elements

Registry commandlumen add CalendarHeatmap

InteractionNative markup

← All chart guides · Framework setup · Native counterparts

01

See it and copy it

Framework example

Explore the live chart, then open its code for Astro, React, or Elements.

AstroCode target · live preview uses Astro

Daily activity

Illustrative contributions · March–August 2026

2026-03-01 – 2026-08-31. Value: 174/184. Not available: 10.

2026-03-01 – 2026-08-31

08× Not available
View chart data
CategoryValue
2026-03-01Not available
2026-03-027
2026-03-035
2026-03-043
2026-03-051
2026-03-068
2026-03-076
2026-03-085
2026-03-093
2026-03-101
2026-03-118
2026-03-126
2026-03-134
2026-03-142
2026-03-151
2026-03-168
2026-03-176
2026-03-184
2026-03-192
2026-03-20Not available
2026-03-217
2026-03-226
2026-03-234
2026-03-242
2026-03-250
2026-03-267
2026-03-275
2026-03-283
2026-03-292
2026-03-300
2026-03-317
2026-04-015
2026-04-023
2026-04-031
2026-04-048
2026-04-057
2026-04-065
2026-04-073
2026-04-08Not available
2026-04-098
2026-04-106
2026-04-114
2026-04-123
2026-04-131
2026-04-148
2026-04-156
2026-04-164
2026-04-172
2026-04-180
2026-04-198
2026-04-206
2026-04-214
2026-04-222
2026-04-230
2026-04-247
2026-04-255
2026-04-264
2026-04-27Not available
2026-04-280
2026-04-297
2026-04-305
2026-05-013
2026-05-021
2026-05-030
2026-05-047
2026-05-055
2026-05-063
2026-05-071
2026-05-088
2026-05-096
2026-05-105
2026-05-113
2026-05-121
2026-05-138
2026-05-146
2026-05-154
2026-05-16Not available
2026-05-171
2026-05-188
2026-05-196
2026-05-204
2026-05-212
2026-05-220
2026-05-237
2026-05-246
2026-05-254
2026-05-262
2026-05-270
2026-05-287
2026-05-295
2026-05-303
2026-05-312
2026-06-010
2026-06-027
2026-06-035
2026-06-04Not available
2026-06-051
2026-06-068
2026-06-077
2026-06-085
2026-06-093
2026-06-101
2026-06-118
2026-06-126
2026-06-134
2026-06-143
2026-06-151
2026-06-168
2026-06-176
2026-06-184
2026-06-192
2026-06-200
2026-06-218
2026-06-226
2026-06-23Not available
2026-06-242
2026-06-250
2026-06-267
2026-06-275
2026-06-284
2026-06-292
2026-06-300
2026-07-017
2026-07-025
2026-07-033
2026-07-041
2026-07-050
2026-07-067
2026-07-075
2026-07-083
2026-07-091
2026-07-108
2026-07-116
2026-07-12Not available
2026-07-133
2026-07-141
2026-07-158
2026-07-166
2026-07-174
2026-07-182
2026-07-191
2026-07-208
2026-07-216
2026-07-224
2026-07-232
2026-07-240
2026-07-257
2026-07-266
2026-07-274
2026-07-282
2026-07-290
2026-07-307
2026-07-31Not available
2026-08-013
2026-08-022
2026-08-030
2026-08-047
2026-08-055
2026-08-063
2026-08-071
2026-08-088
2026-08-097
2026-08-105
2026-08-113
2026-08-121
2026-08-138
2026-08-146
2026-08-154
2026-08-163
2026-08-171
2026-08-188
2026-08-19Not available
2026-08-204
2026-08-212
2026-08-220
2026-08-238
2026-08-246
2026-08-254
2026-08-262
2026-08-270
2026-08-287
2026-08-295
2026-08-304
2026-08-312
View CalendarHeatmap code

Framework usage

Switch targets to compare the adapter code. This live preview runs the Astro example. React and Elements use their own behavior APIs; complete the matching framework setup before copying an example.
astro
---
import { CalendarHeatmap } from '@santi020k/lumen-astro'

// Illustrative daily observations, including real zeros and missing values.
const data = Array.from({ length: 184 }, (_, index) => ({
  date: new Date(Date.UTC(2026, 2, index + 1)).toISOString().slice(0, 10),
  value: index % 19 === 0 ? null : (index * 7 + Math.floor(index / 7)) % 9
}))
---

<CalendarHeatmap
  aria-label="Daily activity"
  heading="Daily activity"
  description="Illustrative contributions · March–August 2026"
  data={data}
  startDate="2026-03-01"
  endDate="2026-08-31"
  weekStartsOn={1}
/>
Edit CalendarHeatmap in browser

When to use CalendarHeatmap

Use for daily activity, contributions, attendance, or another measure with one observation per calendar date.

  • Each cell represents a day; color represents magnitude. A measured zero remains distinct from a missing date.
  • Use formatDate and formatValue for localized output. A supplied domain must be increasing and enclose every observed value.
  • When formatting date-only identities with Intl.DateTimeFormat, specify timeZone: 'UTC' so local time zones do not shift the calendar day.

Prepare the data

ts
import type { LumenCalendarHeatmapDatum } from '@santi020k/lumen-core'

const startDate = '2026-08-01'
const endDate = '2026-08-07'
const data = [
  { date: '2026-08-01', value: 3 },
  { date: '2026-08-02', value: 0 },
  { date: '2026-08-03', value: null },
  { date: '2026-08-07', value: 6 }
] satisfies readonly LumenCalendarHeatmapDatum[]
  • startDate and endDate define an inclusive YYYY-MM-DD Gregorian range of at most 3660 days. Date identity is independent of locale and time zone.
  • Each supplied date must be unique and inside that range. Values are finite numbers or null; omitted dates remain missing.
  • Set weekStartsOn to 0 for Sunday or 1 for Monday. A custom weekdayLabels array always uses Sunday-first indexing, regardless of the first displayed day.

Shared data and formatting guidance →

Avoid misleading comparisons

  • Do not pass timestamp strings in place of date-only identities. Convert events into the intended reporting date and aggregate them before rendering.
  • Automatic color domains can differ between periods. Use a shared domain when comparing two calendars.

Chart accessibility and keyboard guidance →

02

Choose your target

Add this component

Choose the package for your runtime. All adapters share the Lumen stylesheet. Use the matching registry command when you want a local wrapper for that framework.

bash@santi020k/lumen-astro
pnpm add @santi020k/lumen-astro
pnpm add @santi020k/lumen-astro
bashAstro wrapper
lumen add CalendarHeatmap
lumen add CalendarHeatmap

API reference

Lumen-specific props and runtime attributes for the Astro primitive. Use the framework differences above and the copyable examples for React composition and Elements attributes; the public adapter types define their supported contracts.

AttributeValuesDefaultDescription
datareadonly LumenCalendarHeatmapDatum[]requiredISO date-only identities and nullable finite values. Omitted dates remain missing.
startDate, endDateYYYY-MM-DDrequiredInclusive Gregorian range, at most 3660 days. Duplicate or out-of-range observations are invalid.
weekStartsOn0 | 10Sunday or Monday. weekdayLabels always uses Sunday-first indexing.
domainLumenChartDomainautomaticFinite increasing domain enclosing every supplied observation.
formatDate, formatValue, weekdayLabels, labelsFormatters and localized labelsdate identity / EnglishFormats the date range, axes, summary and exact data alternative.
showTablebooleantrueShows a keyboard-accessible table; hidden tables retain an exact screen-reader alternative.
class, classNamestring""Merges custom classes with the generated ui-* root classes.
...native attributesHTML attributes-Forwards standard attributes to the root element unless the component consumes them.

Web docsFull catalog