Docs
Data

Activity Heatmap

A streak calendar in steps of red with a glass streak chip, and a scrub that lifts each day with a callout and a haptic tick.

$npx swiftpieces add ActivityHeatmap
See it in a Pro app On a real screen in one of the Pro apps: open it with Pro, take it apart, remix it, and copy the SwiftUI.
Free · MIT + Commons ClauseiOS 17.0+Liquid Glassheatmapstreakcalendarhabitsactivitycontributionsscrubaccessibility
Type
ActivityHeatmap
Files
ActivityHeatmap.swift
Depends on
Nothing (Apple frameworks only)
Version
1.3.0
In a full screen · SwiftPieces ProLessonsA language-learning home with a streak, today's goals as color blocks and a floating tab bar whose lens follows your finger.

A calendar heatmap of daily activity with the current streak, a scrub callout and full VoiceOver support. Columns are weeks, oldest leading and newest trailing, and rows are weekdays in the calendar's order, so Monday-first regions get Monday on top. Each day is one rounded cell: level 0 is an empty field and levels 1 to 4 are solid steps of the accent mixed into the ground, up to the pure accent. Drag sideways across the grid, or press and move, to read any day, and tap to select one; vertical swipes still scroll the screen. When the weeks outgrow the width the grid scrolls sideways and a short hold starts the reading instead. The cells are drawn in one Canvas and hit-tested by geometry, so a year of days stays light. The cells are content; the chrome around them is liquid glass. The streak label and the legend sit on glass chips, and a selected day lifts out of the grid as a glass tile tinted with its shade, with its callout budding out of it and resting joined to it by a liquid neck. The callout melts back into the tile when the day is let go.

Notes

  • Pass activity keyed by day as [Date: Double] or [Date: Int]. Each key lands on the day it falls on in the calendar's time zone, so exact timestamps work and several entries on one day add up. Zero, negative and non-finite values count as no activity. If you store days as midnight UTC, pass a calendar whose time zone is UTC.
  • Columns are weeks, oldest leading and newest trailing, and rows are weekdays in the calendar's order: the person's own first weekday by default, so Monday-first regions get Monday on top. Days are stepped from noon, so daylight saving changes and leap days never skip or double a cell. Month labels sit above the first week of each month, and the weekday labels mark Monday, Wednesday and Friday on whichever rows they fall.
  • Level 0 is the empty field. Levels 1 to 4 are solid steps of the accent mixed into the ground (pale on light, deep on dark, further apart with Increase Contrast), up to the pure accent, never transparency. .automatic splits the non-zero days in view into quartiles, so one huge day does not wash out the rest and the busiest day always takes the top shade. .thresholds([1, 3, 6, 10]) sets the minimum for each level; fewer than four spread over the shades, so .thresholds([1]) draws a done or not done habit in the full accent.
  • The current streak counts back from today and stays alive until midnight while today has nothing yet. It looks back through all of your data, so a streak that began before the first visible week is counted in full; the longest streak and the active days cover the visible weeks. With .thresholds, the first value is what counts as active. ActivityHeatmap.summary(of:) returns the same figures for a widget or a reminder.
  • Drag sideways across the grid, or press and move, and the day under the finger is plucked up out of the still grid as a glass tile tinted with its shade, with a selection tick for each new day. It springs up with visible give, and its callout (date, value and its shade, on glass) buds out of it: born inside the day, it springs out to rest just above it (or below, near the top), joined to the day by a liquid neck that points it at its day. Both glide from day to day on a spring that never bounces or trails the finger, while the callout's text changes at once, so a fast scrub never ghosts. Let go, the callout's text blurs off and it melts back into the day, which settles onto the grid and leaves. Vertical swipes that start on the grid still scroll the screen or move a sheet. Tap a day to select it and tap it again to clear it.
  • With a selection binding, a scrub moves the selection live and release keeps it; setting it from outside selects that day and scrolls it into view. Without a binding, a scrub shows the callout only while the finger is down, and a tap keeps it.
  • Cells grow to fill the width up to Style.maximumCellSize. When the weeks would make them smaller than Style.minimumCellSize, the grid scrolls sideways, opens on today and comes to rest on whole weeks; sideways swipes scroll it and a quarter-second hold starts reading instead, with a soft tap in place of the first day's tick.
  • Today wears a ring in the text color, and days after the end date are left out. endDate shows an earlier range; nil (the default) follows today and moves on by itself at midnight or when the time zone changes.
  • The current streak's label sits on a glass chip, its flame lit in the accent while the streak is alive (lit and unlit blur across), and the legend sits on a glass chip under the grid. Every string and symbol is semibold; size sets the hierarchy.
  • On first appearance the empty tiles are there at once and the shades grow into them in a wave, oldest week to newest, stopping at their tile's size so none ever reads larger; today's ring is there from the start. A whole new dataset (more than 21 days changed) grows in the same way. A day whose value changes is kicked up off its tile and settles with a little give while its neighbors stay still, and the streak numeral and figures roll to their new values. Under Reduce Motion the shades are simply there, a changed day is marked by a faint ring just inside its tile that fades instead of the pop (so it shows on today too), the lifted day sits at a smaller lift without springing and moves from day to day at once, the callout fades in and out in place instead of budding, the numerals crossfade, and a selection set from outside jumps into view instead of scrolling.
  • VoiceOver reads the heatmap as one adjustable element: "Activity, last 20 weeks. Current streak 12 days. Longest 31 days. Active 86 days." Swipe up or down to move a day (the value reads "Tuesday, September 30, 45 min"), use the Previous week and Next week actions, and the escape gesture clears the selection. It also offers the days as an audio graph. With a hardware keyboard, the up and down arrows move a day and left and right move a week.
  • While your data loads, apply .redacted(reason: .placeholder): the grid keeps its shape in empty cells and the figures redact. With no activity in view the summary reads "No activity yet".
  • Dynamic Type scales the streak, the figures and the labels; the summary stacks at large sizes and the grid labels stop growing before they crowd the rows, while cells keep their size. Right to left, the weeks run from the right, newest on the left.
  • Style sets the accent, the ground the shades are mixed into (set it to the surface the heatmap sits on), the empty, text, secondary and callout colors, the cell radius and spacing, the smallest and largest cell, and the numeral size. callout tints the callout's glass (.clear, the default, leaves it neutral) and calloutText colors its text (the text color by default). Under Reduce Transparency the glass draws solid. Style.fill(level:) gives the same shades for your own day details. Messages replaces any line of built-in copy, and valueLabel names your unit, for example minutes formatted as a Measurement.

Usage

ActivityHeatmapExample()

Parameters

ParameterDescription
countsActivity per day, such as sessions, minutes or entries. Each key is placed on the day it falls on in calendar (its time zone), so exact timestamps work and several on one day add up. Zero, negative and non-finite values count as no activity. Days outside the visible weeks are ignored, except that a current streak which began earlier is counted in full. [Date: Int] works too.
weeksHow many week columns to show. Defaults to 20. Cells grow to fill the width up to Style.maximumCellSize; when they would fall below Style.minimumCellSize the grid scrolls sideways and opens on the newest week.
endDateThe last day shown; later days in its week are left out. nil (the default) is today, and the grid moves on by itself at midnight.
calendarThe calendar for days, weeks and the first weekday. nil (the default) uses the environment's calendar, which is the person's own.
levelsHow values map to the four shades. .automatic splits the non-zero days in view into quartiles. .thresholds([1, 3, 6, 10]) sets the minimum for each level, and its first value is also what counts as an active day for streaks.
showsSummaryShows the current streak, the longest streak and the number of active days above the grid.
selectionThe selected day, as the start of that day. Tapping a day selects it and tapping it again clears it; with a binding, a scrub moves it live and release keeps it. Without a binding, a scrub shows the callout only while the finger is down. Setting it from outside selects that day and scrolls it into view.
messagesBuilt-in copy. Defaults are localizable through your String Catalog; replace any line, for example title with "Workouts".
styleColors and cell metrics. Defaults to the SwiftPieces house palette with a red accent, adapting to light and dark.
valueLabelHow a day's value reads in the callout and to VoiceOver, for example minutes formatted as a Measurement. Defaults to the plain number. Days with no activity read messages.noActivity.

Install

Pick one. Run it from the folder that contains your .xcodeproj and the files land inside your app.

Terminal

$npx swiftpieces add ActivityHeatmap

Or ask your coding agent · Claude Code, Cursor or Xcode, once the MCP server is connected

>Add the SwiftPieces "Activity Heatmap" piece to my app

Or copy the source above into your app.

New to SwiftUI?If you know React, CSS or Tailwind, SwiftUI is easier to pick up than it looks.Try real app patterns first

Building a whole app? See SwiftPieces Pro →

All data and charts →

Build it yourself: SwiftUI animations guide

On this page

SwiftPiecesPro

Build the whole app with one library.

Production-ready screens, whole flows, complete app templates, a Build Kit your agent follows and Pro remixing.

Explore Pro