Activity Heatmap HTML CSS JS — GitHub-Style Calendar

The GitHub contribution graph is one of the most recognized data visualizations in developer tools. Its 52-column × 7-row grid of colored squares communicates an entire year of activity at a single glance — no axes, no numbers, no scrolling. The intensity of each cell encodes a count, so patterns like streaks, weekday vs weekend habits, and seasonal dips emerge immediately from the visual texture.

This snippet replicates that pattern in pure HTML, CSS, and vanilla JavaScript — no D3, no charting library, no canvas. It renders a full 364-day (52 weeks) heatmap with five color intensity tiers, month labels above the grid, day labels on the left, and a hover tooltip showing the exact count and date.

Data Model and Date Generation

The heatmap data is a plain JavaScript object where each key is an ISO date string in YYYY-MM-DD format and each value is an activity count (any non-negative integer). The generateData() function populates this object for the 364 days before today: it counts backwards from today using setDate(today.getDate() - offset) and formats each date as d.toISOString().slice(0, 10).

The distribution is deliberately skewed: approximately 40% of days get a count of 0 (the Math.random() < 0.4 branch), and the remaining 60% get a count from 1 to 20 via Math.ceil(Math.random() * 20). This produces realistic-looking sparse activity rather than a uniform fill.

Quartile-Based Color Tier Binning

Rather than using a fixed scale (e.g., 1–4 = tier 1, 5–9 = tier 2), the snippet uses quartile binning: it collects all non-zero counts, sorts them ascending, and divides the sorted array into four equal quartile buckets. The thresholds are at indices 25%, 50%, and 75% of the sorted array. Any count that falls below the 25th percentile gets tier 1 (lightest), above the 75th gets tier 4 (darkest), and the middle two quartiles get tiers 2 and 3.

This adaptive approach means the color distribution always looks balanced regardless of the actual count magnitude — whether your data ranges from 1–5 or 1–500, the heatmap uses all four non-empty colors. The buildTiers(data) function returns a function tier(count) that takes a count and returns the tier index 0–4 (0 for zero counts).

CSS Grid Layout for the Cell Matrix

The core grid uses CSS: display: grid; grid-template-columns: repeat(52, 11px); grid-auto-rows: 11px; gap: 2px. The 52 columns represent weeks and the 7 rows (auto-generated) represent days. Each cell is an 11×11px div.

The key layout detail is column-first ordering: cells are appended in day order (day 0 of week 0, day 1 of week 0, ..., day 6 of week 0, day 0 of week 1, ...) so CSS Grid naturally flows them into the right column-per-week arrangement. The grid-auto-flow: column equivalent is achieved by setting 52 fixed columns — the browser fills down each column before moving to the next.

Month Label Positioning

Month labels above the grid (Jan, Feb, ..., Dec) are the trickiest part. The label for a given month must appear above the first week-column that starts in that month. For each of the 52 weeks, the snippet checks whether weekStart.getMonth() !== previousWeekStart.getMonth() — if the month changed, that column gets a label. The label div uses absolute positioning with left: (weekIndex * 13)px (column width 11px + gap 2px = 13px per column). The container has position: relative and a fixed height matching the label row.

Day Labels

A separate flex column on the left shows Mon, Wed, Fri at indices 1, 3, 5 (the even-index days are left blank for a GitHub-faithful look). Each label is 11px tall plus 2px gap, aligned to the corresponding grid row.

Hover Tooltip

The tooltip is a single absolutely-positioned div that moves with the mouse. Each cell has data-date and data-count attributes set at render time. mouseover reads these via e.target.dataset and updates the tooltip content and position. The tooltip uses position: fixed and offsets from e.clientX and e.clientY with a 10px nudge to avoid covering the hovered cell. mouseleave on the grid container hides it.

Connecting Real Data

To use real contribution data, replace generateData() with a function that builds the same { [YYYY-MM-DD]: count } object from your API. For GitHub contribution data: call the GitHub REST API (/users/{user}/events) or GraphQL API (contributionCalendar) and map each contribution day to its count. For custom apps, aggregate your events table by date server-side and return the result as a JSON object. The rendering code does not care about the source — it only requires the YYYY-MM-DD: count format.

Performance Characteristics

The snippet creates 364 DOM elements on load. This is well within browser performance limits — modern browsers handle thousands of small divs at 60fps without issue. The hover handler is attached once to the parent container (event delegation), not individually to each cell, so there are no 364 separate event listeners in memory. The month-label calculation is O(n) over 52 weeks, not 364 days.