CalendarHeatmap
Shows daily patterns with explicit missing observations.
← All chart guides · Framework setup · Native counterparts
See it and copy it
Framework example
Explore the live chart, then open its code for Astro, React, or Elements.
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
View chart data
| Category | Value |
|---|---|
| 2026-03-01 | Not available |
| 2026-03-02 | 7 |
| 2026-03-03 | 5 |
| 2026-03-04 | 3 |
| 2026-03-05 | 1 |
| 2026-03-06 | 8 |
| 2026-03-07 | 6 |
| 2026-03-08 | 5 |
| 2026-03-09 | 3 |
| 2026-03-10 | 1 |
| 2026-03-11 | 8 |
| 2026-03-12 | 6 |
| 2026-03-13 | 4 |
| 2026-03-14 | 2 |
| 2026-03-15 | 1 |
| 2026-03-16 | 8 |
| 2026-03-17 | 6 |
| 2026-03-18 | 4 |
| 2026-03-19 | 2 |
| 2026-03-20 | Not available |
| 2026-03-21 | 7 |
| 2026-03-22 | 6 |
| 2026-03-23 | 4 |
| 2026-03-24 | 2 |
| 2026-03-25 | 0 |
| 2026-03-26 | 7 |
| 2026-03-27 | 5 |
| 2026-03-28 | 3 |
| 2026-03-29 | 2 |
| 2026-03-30 | 0 |
| 2026-03-31 | 7 |
| 2026-04-01 | 5 |
| 2026-04-02 | 3 |
| 2026-04-03 | 1 |
| 2026-04-04 | 8 |
| 2026-04-05 | 7 |
| 2026-04-06 | 5 |
| 2026-04-07 | 3 |
| 2026-04-08 | Not available |
| 2026-04-09 | 8 |
| 2026-04-10 | 6 |
| 2026-04-11 | 4 |
| 2026-04-12 | 3 |
| 2026-04-13 | 1 |
| 2026-04-14 | 8 |
| 2026-04-15 | 6 |
| 2026-04-16 | 4 |
| 2026-04-17 | 2 |
| 2026-04-18 | 0 |
| 2026-04-19 | 8 |
| 2026-04-20 | 6 |
| 2026-04-21 | 4 |
| 2026-04-22 | 2 |
| 2026-04-23 | 0 |
| 2026-04-24 | 7 |
| 2026-04-25 | 5 |
| 2026-04-26 | 4 |
| 2026-04-27 | Not available |
| 2026-04-28 | 0 |
| 2026-04-29 | 7 |
| 2026-04-30 | 5 |
| 2026-05-01 | 3 |
| 2026-05-02 | 1 |
| 2026-05-03 | 0 |
| 2026-05-04 | 7 |
| 2026-05-05 | 5 |
| 2026-05-06 | 3 |
| 2026-05-07 | 1 |
| 2026-05-08 | 8 |
| 2026-05-09 | 6 |
| 2026-05-10 | 5 |
| 2026-05-11 | 3 |
| 2026-05-12 | 1 |
| 2026-05-13 | 8 |
| 2026-05-14 | 6 |
| 2026-05-15 | 4 |
| 2026-05-16 | Not available |
| 2026-05-17 | 1 |
| 2026-05-18 | 8 |
| 2026-05-19 | 6 |
| 2026-05-20 | 4 |
| 2026-05-21 | 2 |
| 2026-05-22 | 0 |
| 2026-05-23 | 7 |
| 2026-05-24 | 6 |
| 2026-05-25 | 4 |
| 2026-05-26 | 2 |
| 2026-05-27 | 0 |
| 2026-05-28 | 7 |
| 2026-05-29 | 5 |
| 2026-05-30 | 3 |
| 2026-05-31 | 2 |
| 2026-06-01 | 0 |
| 2026-06-02 | 7 |
| 2026-06-03 | 5 |
| 2026-06-04 | Not available |
| 2026-06-05 | 1 |
| 2026-06-06 | 8 |
| 2026-06-07 | 7 |
| 2026-06-08 | 5 |
| 2026-06-09 | 3 |
| 2026-06-10 | 1 |
| 2026-06-11 | 8 |
| 2026-06-12 | 6 |
| 2026-06-13 | 4 |
| 2026-06-14 | 3 |
| 2026-06-15 | 1 |
| 2026-06-16 | 8 |
| 2026-06-17 | 6 |
| 2026-06-18 | 4 |
| 2026-06-19 | 2 |
| 2026-06-20 | 0 |
| 2026-06-21 | 8 |
| 2026-06-22 | 6 |
| 2026-06-23 | Not available |
| 2026-06-24 | 2 |
| 2026-06-25 | 0 |
| 2026-06-26 | 7 |
| 2026-06-27 | 5 |
| 2026-06-28 | 4 |
| 2026-06-29 | 2 |
| 2026-06-30 | 0 |
| 2026-07-01 | 7 |
| 2026-07-02 | 5 |
| 2026-07-03 | 3 |
| 2026-07-04 | 1 |
| 2026-07-05 | 0 |
| 2026-07-06 | 7 |
| 2026-07-07 | 5 |
| 2026-07-08 | 3 |
| 2026-07-09 | 1 |
| 2026-07-10 | 8 |
| 2026-07-11 | 6 |
| 2026-07-12 | Not available |
| 2026-07-13 | 3 |
| 2026-07-14 | 1 |
| 2026-07-15 | 8 |
| 2026-07-16 | 6 |
| 2026-07-17 | 4 |
| 2026-07-18 | 2 |
| 2026-07-19 | 1 |
| 2026-07-20 | 8 |
| 2026-07-21 | 6 |
| 2026-07-22 | 4 |
| 2026-07-23 | 2 |
| 2026-07-24 | 0 |
| 2026-07-25 | 7 |
| 2026-07-26 | 6 |
| 2026-07-27 | 4 |
| 2026-07-28 | 2 |
| 2026-07-29 | 0 |
| 2026-07-30 | 7 |
| 2026-07-31 | Not available |
| 2026-08-01 | 3 |
| 2026-08-02 | 2 |
| 2026-08-03 | 0 |
| 2026-08-04 | 7 |
| 2026-08-05 | 5 |
| 2026-08-06 | 3 |
| 2026-08-07 | 1 |
| 2026-08-08 | 8 |
| 2026-08-09 | 7 |
| 2026-08-10 | 5 |
| 2026-08-11 | 3 |
| 2026-08-12 | 1 |
| 2026-08-13 | 8 |
| 2026-08-14 | 6 |
| 2026-08-15 | 4 |
| 2026-08-16 | 3 |
| 2026-08-17 | 1 |
| 2026-08-18 | 8 |
| 2026-08-19 | Not available |
| 2026-08-20 | 4 |
| 2026-08-21 | 2 |
| 2026-08-22 | 0 |
| 2026-08-23 | 8 |
| 2026-08-24 | 6 |
| 2026-08-25 | 4 |
| 2026-08-26 | 2 |
| 2026-08-27 | 0 |
| 2026-08-28 | 7 |
| 2026-08-29 | 5 |
| 2026-08-30 | 4 |
| 2026-08-31 | 2 |
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.---
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}
/>import { CalendarHeatmap } from '@santi020k/lumen-react'
// 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
}))
export const Example = () => (
<>
<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}
/>
</>
)<script type="module">
import { defineLumenElements } from '@santi020k/lumen-elements/define'
defineLumenElements(['CalendarHeatmap'])
</script>
<lumen-calendar-heatmap id="example-calendar-heatmap"
aria-label="Daily activity"
heading="Daily activity"
description="Illustrative contributions · March–August 2026"
start-date="2026-03-01"
end-date="2026-08-31"
week-starts-on="1"></lumen-calendar-heatmap>
<script type="module">
"use strict";
// 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
}));
const chart = document.getElementById('example-calendar-heatmap')
chart?.setAttribute('data', JSON.stringify(data))
</script>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
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.
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.
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.
pnpm add @santi020k/lumen-astropnpm add @santi020k/lumen-astrolumen add CalendarHeatmaplumen add CalendarHeatmappnpm add @santi020k/lumen-reactpnpm add @santi020k/lumen-reactlumen add CalendarHeatmap --target reactlumen add CalendarHeatmap --target reactpnpm add @santi020k/lumen-elementspnpm add @santi020k/lumen-elementslumen add CalendarHeatmap --target elementslumen add CalendarHeatmap --target elementsAPI 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.
| Attribute | Values | Default | Description |
|---|---|---|---|
| data | readonly LumenCalendarHeatmapDatum[] | required | ISO date-only identities and nullable finite values. Omitted dates remain missing. |
| startDate, endDate | YYYY-MM-DD | required | Inclusive Gregorian range, at most 3660 days. Duplicate or out-of-range observations are invalid. |
| weekStartsOn | 0 | 1 | 0 | Sunday or Monday. weekdayLabels always uses Sunday-first indexing. |
| domain | LumenChartDomain | automatic | Finite increasing domain enclosing every supplied observation. |
| formatDate, formatValue, weekdayLabels, labels | Formatters and localized labels | date identity / English | Formats the date range, axes, summary and exact data alternative. |
| showTable | boolean | true | Shows a keyboard-accessible table; hidden tables retain an exact screen-reader alternative. |
| class, className | string | "" | Merges custom classes with the generated ui-* root classes. |
| ...native attributes | HTML attributes | - | Forwards standard attributes to the root element unless the component consumes them. |