Heatmap

Installation

pnpm dlx @mielui/svelte add heatmap

npx @mielui/svelte add heatmap

yarn dlx @mielui/svelte add heatmap

bunx @mielui/svelte add heatmap

Usage

Pass daily counts with dates in YYYY-MM-DD format. Root renders the complete calendar when it has no children. No GitHub connection is required.

<script lang="ts">
    import * as Heatmap from '@mielui/svelte/components/heatmap';

    const days = [
        {
            date: '2026-09-14',
            count: 4
        },
        {
            date: '2026-09-15',
            count: 12
        }
    ];
</script>

<Heatmap.Root {days} endDate="2026-09-15" weeks={12} />

Without a tooltip

The automatic layout includes Tooltip. In a custom layout, omit it to keep native browser titles instead. Every cell keeps its accessible date and count label.

<Heatmap.Root {days} weeks={12} endDate="2026-09-15">
    <Heatmap.Calendar>
        <Heatmap.MonthLabels />
        <Heatmap.WeekdayLabels />
        <Heatmap.Grid />
    </Heatmap.Calendar>
    <Heatmap.Detail />
</Heatmap.Root>

Data and range

Root takes days, loading, weeks, endDate, weekStartsOn, locale, animation, and onDaySelect. weeks defaults to 26 and accepts 1 to 104. weekStartsOn defaults to 0, Sunday, and accepts 0 through 6. locale formats month and weekday names and defaults to en-US.

Dates use UTC. Input order does not matter, missing dates count as zero, and the last entry wins when a date repeats. endDate defaults to the latest supplied date, or today for an empty dataset; set it for a stable reporting period.

The calendar starts at the beginning of the first week and stops at endDate. Totals include only visible dates. Counts must be finite and non-negative. An optional level from 0 to 4 sets a day's intensity; otherwise intensity follows the largest visible count. Invalid values throw a RangeError.

Animation

animation defaults to rows. Choose columns for a left-to-right stagger, live for a repeating column highlight, or none to render immediately. Live motion keeps the counts unchanged and pauses during inspection, offscreen, and in hidden documents. Entrance timing follows the theme's motion setting, and reduced motion skips the entrance.

Parts

Root owns the data and passes days and total to its children snippet. Header, Calendar, and Footer arrange content. Summary passes its total to a children snippet. Grid passes the computed days to a children snippet; render a Cell for each. Detail passes the active day to a children snippet.

MonthLabels, WeekdayLabels, and Legend render default labels that children can replace. Each part accepts native attributes and class. Keep Grid inside Calendar so the month and weekday labels line up.

Keyboard and accessibility

Tab enters the calendar once. Arrow keys move between dates, Home focuses the first visible date, and End the last. Left and right follow the layout in RTL. Each cell announces its full date and count, so color is not the only source of information.

Hover or focus updates Detail and opens Tooltip; Escape closes the tooltip. Activating a cell calls onDaySelect with the computed day.

Labels

Built-in text is English. Pass a labels object to Root to translate the unit in cell labels and the summary (unit, a function of the count), the tooltip heading (tooltipValue), the legend ends (less, more), the grid's accessible name in each state (grid, gridLoading, gridEmpty), the detail line while loading or empty (detailLoading, detailEmpty), and the summary before data is ready (summaryPending). HeatmapLabels types it; every key is optional.

<Heatmap.Root
    {days}
    labels={{
        unit: (count) => (count === 1 ? 'commit' : 'commits'),
        less: 'Moins',
        more: 'Plus'
    }}
/>