Heatmap Tracker

Turn any dated note into a beautiful, interactive heatmap — habits, workouts, mood, finances, work logs, anything.

Website · Install · Quick start · Configuration · Export · FAQ · Example vault

---

What it does

You already write things down in Obsidian. Heatmap Tracker reads those notes and turns them into a year-at-a-glance grid — the kind you know from GitHub's contribution graph, but for your data, in your vault, with no account and no cloud.

Add steps: 8420 to a daily note and you get a heatmap. Add mood: 4 and you get another. Every filled square is clickable and opens the note behind it; every empty square offers to create it.

• Zero-config for frontmatter. Run Insert Heatmap Tracker, fill in a form with a live preview, done — no YAML, no JavaScript. Every heatmap stays editable from the same form.
• Fully scriptable when you need it. A dataviewjs escape hatch gives you complete control over the dataset.
• Everything stays local. Your notes are the database.

---

📋 Table of contents

• Install
• Quick start
• Use cases
• Codeblock usage
• Advanced usage (dataviewjs)
• Migrating from Heatmap Calendar
• Configuration reference
• Export a report
• Features
• FAQ & troubleshooting
• How it compares
• Development
• Contributing
• Support the project
• License & credits

---

📥 Install

From Obsidian (recommended)

1. Open Settings → Community plugins and make sure Restricted mode is off.
2. Click Browse, search for “Heatmap Tracker”.
3. Click Install, then Enable.

Or open this link from inside Obsidian: Install Heatmap Tracker.

Install Dataview (required)

Heatmap Tracker uses Dataview to read data out of your notes. Install and enable it the same way. For the dataviewjs examples below, also enable Dataview → Settings → Enable JavaScript Queries.

Manual install

1. Download main.js, styles.css and manifest.json from the latest release.
2. Put them in <your-vault>/.obsidian/plugins/heatmap-tracker/.
3. Reload Obsidian and enable the plugin in Community plugins.

Beta versions via BRAT

Install BRAT, then run BRAT: Add a beta plugin for testing and enter mokkiebear/heatmap-tracker.

Requirements: Obsidian 1.4.0+, desktop and mobile, Dataview plugin.

---

🚀 Quick start

1. Put a value in a daily note. In 2026-08-04.md:

---
steps: 8420
---

Numbers work (steps: 8420), and so do booleans — meditated: true simply counts as 1.

2. Add the heatmap — use the modal. Run Insert Heatmap Tracker from the command palette, or click the Heatmap Tracker icon in the left ribbon. This is the recommended way to use the plugin: the form has a live preview, tells you how many notes currently match, and writes the codeblock for you. Everything beyond the essentials is tucked into collapsed sections, so you only see what you need.

Changed your mind later? Hover any rendered heatmap and click the pencil in its corner — the same form reopens with that heatmap's settings and rewrites its codeblock on save. No hand-editing YAML.

If you'd rather write it by hand, the codeblock is plain YAML:

```heatmap-tracker
property: steps
```

3. That's it. Switch years with the arrows, hover a square for details, click one to open the note.

[!TIP] The Example Vault is a full working vault you can open in Obsidian — copy-pasteable examples for every parameter, plus ready-made trackers for habits, mood, sleep, water intake and projects. It's updated often.

---

💡 Use cases

Every one of these has a working example in the Example Vault.

---

🧩 Codeblock usage

The heatmap-tracker codeblock handles frontmatter tracking out of the box. The Insert Heatmap Tracker modal writes and edits it for you — the reference below is for anyone who prefers typing YAML, or wants to know what the modal produces.

Single property

```heatmap-tracker
property: exercise
```

This looks for exercise in your notes and lights up a square wherever it's set.

Multiple properties

```heatmap-tracker
property: [running, cycling, swimming]
```

Values from all listed properties are aggregated into one heatmap.

Narrowing down which notes count

path, tags and filters are all optional and can be combined:

```heatmap-tracker
property: exercise
path: "daily notes"
tags: [journal]
filters:
  - property: status
    operator: equals
    value: done
```

Each filters entry takes:

• property — the frontmatter key to check.
• operator — equals, contains, or notEmpty.
• value — compared against the property's value (not needed for notEmpty).

---

⚙️ Advanced usage (dataviewjs)

When you need full control over the dataset — computed values, external sources, custom colors per entry — use a dataviewjs codeblock:

```dataviewjs
// Update this object
const trackerData = {
    entries: [],
    separateMonths: true,
    heatmapTitle: "This is the title for your heatmap",
    heatmapSubtitle: "This is the subtitle for your heatmap. You can use it as a description.",
}

// Path to the folder with notes
const PATH_TO_YOUR_FOLDER = "daily notes preview/notes";
// Name of the parameter you want to see on this heatmap
const PARAMETER_NAME = 'steps';

// You need dataviewjs plugin to get information from your pages
for (let page of dv.pages(`"${PATH_TO_YOUR_FOLDER}"`).where((p) => p[PARAMETER_NAME])) {
    trackerData.entries.push({
        date: page.file.name,
        // Use absolute file path so clicks open the exact note
        // (matters when several notes share a name)
        filePath: page.file.path,
        intensity: page[PARAMETER_NAME],
    });
}

// Optional: set base path so new files are created here if missing
trackerData.basePath = PATH_TO_YOUR_FOLDER;

renderHeatmapTracker(this.container, trackerData);
```

How clicking a square resolves a file

1. If the entry has filePath (page.file.path), that exact file opens. Missing? The plugin offers to create it at the same path.
2. Otherwise, if trackerData.basePath is set, it proposes creating/opening basePath/YYYY-MM-DD.md.
3. Otherwise it falls back to your Daily Notes settings (folder + format) via the Daily Notes API.

The note opens in the active tab; Cmd/Ctrl + click opens it in a new one, as elsewhere in Obsidian.

[!NOTE] dataviewjs requires Dataview → Settings → Enable JavaScript Queries. The plugin also works standalone with any JavaScript that can build an entries array — Dataview is just the most convenient source.

---

🔁 Migrating from Heatmap Calendar

Coming from the unmaintained heatmap-calendar plugin? There is nothing to migrate:

1. Install Heatmap Tracker.
2. Disable Heatmap Calendar.

Your existing renderHeatmapCalendar(...) blocks keep working — Heatmap Tracker provides that function too and maps calendarData onto its own options. Named palettes from the old plugin's settings are read as well, so colors: "blue" still resolves.

Two differences worth knowing:

• Per-entry color is ignored. It named a whole color ramp, and which shade a day got was only decided after intensity mapping; those days now use the main palette. Use customColor: "#ff0000" for a fixed per-day color.
• defaultEntryIntensity, intensityScaleStart and intensityScaleEnd still work, but the current names are intensityConfig.defaultIntensity, .scaleStart and .scaleEnd.

Rewriting a block as renderHeatmapTracker(this.container, trackerData) gets you the rest: statistics, legend, month/week layouts, clickable squares.

---

📖 Configuration reference

The authoritative reference for every trackerData parameter. Each one links to a copy-pasteable example in the Example Vault.

At a glance

year

• Type: number
• Default: Current year (new Date().getFullYear())
• Description: The year the heatmap displays by default.
• Example: year

---

heatmapTitle

• Type: string | number
• Default: undefined
• Description: Title displayed above the heatmap. Supports HTML for custom styling.
• Example: heatmapTitle

---

heatmapSubtitle

• Type: string | number
• Default: undefined
• Description: Subtitle/description displayed under the title. Supports HTML for custom styling.
• Example: heatmapSubtitle

---

colorScheme

• Type: object
• Default:

{
  paletteName: "default",
  customColors: []
}

• Description: The color scale used to represent intensity levels. Each color maps to a range of data intensity. Use paletteName to reference a palette defined in plugin settings, or customColors to pass your own array of colors inline.
• Example: colorScheme

---

customColor

• Type: string
• Default: undefined
• Description: An entry property (set on an item inside entries, not on trackerData itself). Sets the color for that specific entry, overriding colorScheme.

---

entries

• Type: array
• Default:

[
  { date: "1900-01-01", customColor: "#7bc96f", intensity: 5, content: "" }
]

• Description: The list of data points. Each entry supports:

• Example: entries

Accepted date formats

date is parsed by the plugin itself, so a note renders identically on desktop, iOS and Android. Accepted:

Anything else (March 2025, 31.01.25, a raw Date object) is rejected and the entry is dropped. Prefer YYYY-MM-DD: 01-02-2025 is read as January 2nd, which is not what a European reader means by it.

Emoji habit tracking

Set emoji on an entry to draw a glyph inside that day's box. The box keeps its palette color, so "which habit" and "how much" are readable at the same time — useful for yes/no habits where a color gradient says little.

const trackerData = {
  entries: [],
  heatmapTitle: "Habits",
  colorScheme: { customColors: ["#c6e48b", "#7bc96f", "#239a3b"] },
};

for (const page of dv.pages('"Daily"').where(p => p.workout || p.reading)) {
  trackerData.entries.push({
    date: page.file.name,
    intensity: 1,
    emoji: page.workout ? "🏃" : "📖",
    filePath: page.file.path,
  });
}

renderHeatmapTracker(this.container, trackerData);

Notes:

• Keep it to one glyph. The box is 12px by default, so the value is capped at 8 characters and validation rejects longer strings rather than drawing unreadable pixels. Use content for text.

• emoji and content are different fields, and complement each other. emoji is the marker; content is what happened that day. Only content reaches the exported report and screen readers, so a glyph put in content becomes a lone "✅" in your report, while an emoji leaves the report free for the real note text:

  { date: "2025-01-01", emoji: "🏃", content: "5km, felt good" }
  // box shows 🏃 · report says "5km, felt good"
  

• Two entries on one day: only one glyph fits, so the first emoji set for that day is the one drawn.

• Any text works, not just emoji — "✓", "x" and "1" are all valid, and monochrome glyphs get a subtle outline so they stay legible on dark palette colors.

• The glyph is decorative: screen readers announce the date and value from the box's own label and skip it.

---

showCurrentDayBorder

• Type: boolean
• Default: true
• Description: Highlights today's square with a border.
• Example: showCurrentDayBorder

---

intensityConfig

• Type: object
• Default:

{
  scaleStart: undefined,
  scaleEnd: undefined,
  defaultIntensity: 4,
  showOutOfRange: true,
  excludeFalsy: undefined,
  aggregation: "sum"
}

• Description: Configures how entry values map to colors.

aggregation: "average" is for days scored on a rating rather than a total. Tracking hunger-morning and hunger-evening, each 1–10, a day with only a morning entry of 6 sums to 6 out of a possible 20 and renders almost empty; averaged, it scores 6 — the same shade as a day where both readings were 6. Only the values that exist count towards the divisor, so a missing entry doesn't drag the day down:

```heatmap-tracker
property:
  - hunger-morning
  - hunger-evening
intensityConfig:
  aggregation: average
  scaleStart: 1
  scaleEnd: 10
```

Keep the default "sum" for anything cumulative (minutes practised, pages read, steps) — there, two entries on one day genuinely are more than one.

• Example: intensityConfig

[!IMPORTANT] Migrating from defaultEntryIntensity / intensityScaleStart / intensityScaleEnd: these top-level parameters are removed from the API described here. Old codeblocks keep working (they're folded into intensityConfig automatically), but new heatmaps should use intensityConfig directly.

---

basePath

• Type: string
• Default: undefined
• Description: Base folder used to collect entries. When set, the plugin proposes creating new files here when you click an empty square.
• Example: basePath

---

separateMonths

• Type: boolean
• Default: true
• Description: Whether months are visually separated within the heatmap layout.
• Example: separateMonths

---

disableFileCreation

• Type: boolean
• Default: false
• Description: When true, clicking an empty square will not offer to create a new file.
• Example: disableFileCreation

---

insights

• Type: array
• Default: []
• Description: Define your own calculated metrics, displayed in the Statistics tab — most productive day, longest streak, total pages read, average sleep, and anything else you can compute.
• Example: insights · 8 ready-made insights

---

ui

• Type: object
• Default: { defaultView: "heatmap-tracker", hideTabs: false, hideYear: false, hideTitle: false, hideSubtitle: false }
• Description: Per-heatmap chrome. Each key hides a part of the header, or picks which tab opens first — useful for embedding a bare grid in a dashboard note.

ui:
  hideTabs: true
  hideYear: true

---

layout

• Type: "default" | "monthly" | "month" | "week"

• Default: "default"

• Description: Controls the grid arrangement.

  • "default" — the traditional GitHub-style week-column grid.
  • "monthly" — one row per month with days 1–31 as columns; a compact, calendar-style year.
  • "month" — a single calendar month: weekdays as columns, weeks as rows. Shows the current month by default; the header arrows page through months.
  • "week" — a single calendar week: one row of seven days. Shows the current week by default; the header arrows page through weeks.

  "month" and "week" respect the weekStartDay plugin setting. Setting a date range (startDate/endDate, daysToShow, monthsToShow) pins them to that range and hides the arrows.

• Example: layout

---

Date range: monthsToShow, daysToShow, startDate/endDate

These four parameters narrow which dates are displayed instead of the full year. They apply to every layout, including the default week-column grid — which then starts at the range's first day and ends at its last, rather than drawing the whole calendar year. Only one wins when several are set — they resolve in this order (highest priority first):

1. monthsToShow (number, default undefined) — current month plus the N previous months. monthsToShow: 3 displays 4 rows (current month + 3 prior). Best paired with layout: "monthly".
2. daysToShow (number, default undefined) — the last N days ending today. daysToShow: 365 with the default layout gives a rolling year ending on the current week, GitHub-style.
3. startDate + endDate (string, YYYY-MM-DD, default undefined) — an explicit range. Both must be set, and startDate must not be after endDate.

If none are set, the heatmap shows the full year.

This precedence is implemented once, in resolveDateRange — that function's doc comment is the source of truth if this section and the code ever disagree.

• Example: Date range parameters

---

📤 Export a report

Every heatmap has an Export tab alongside Heatmap Tracker / Statistics / Legend / Documentation. It turns your tracked data and daily notes into a single shareable report — a status update, a work log for a manager, an end-of-year summary — sitting between a bare calendar (too little context) and a folder of raw notes (too much noise).

Note content, aggregated. Below the calendar and legend, the report walks every week and day in range and pulls in that day's own note content — frontmatter stripped, bullet points kept as written, a day with no note showing - — grouped under "Week of …" and per-day headings. The reader gets everything that actually happened, day by day, in one document instead of clicking through each note.

Layout. "Weeks as columns" or "Weeks as rows", rendered pixel-for-pixel like the heatmap itself — including exact day-level month splitting (with a year label whenever the range crosses a year boundary) and, when a range is too wide or tall for one grid, automatic wrapping into multiple bands, evenly split rather than front-loading one band and leaving a small leftover.

Date range. Pick start/end dates directly, or jump to a range with a preset: Logged (the full span of your tracked data), Last year, Year to date, Last month, or Month to date.

Display options. Which day the week starts on, whether to show each week's start date, splitting the grid by month, month labels, and hiding weekends.

Legend editor. Colors are pre-populated from what's actually used in your data, so you only fill in what each one means. Reorder entries by drag-and-drop and toggle each category's visibility — shown everywhere, summary-only, or hidden entirely. Optionally combine the intensity colors into a single gradient swatch with one shared label and count, instead of a row per color.

Summary line. A compact, customizable breakdown like Workday: 22 · Leave: 1 · Rest day but worked: 1 with a total (e.g. Total hours: 169) — or hide the breakdown, the total, or all values entirely.

Output. Save as a Markdown note or a self-contained HTML file, to whichever folder in your vault you choose.

All of these preferences persist across sessions, so you only set them up once.

---

📦 Features

Only the essentials are shown up front (properties to track, folder, title); filtering, layout, appearance, intensity and visibility live in collapsed sections.

Every rendered heatmap has a pencil button in its corner: it reopens the same form pre-filled from that codeblock and rewrites it on save.

1. Create your own palette in plugin settings (or use the default).
2. Use customColors in colorScheme to set colors for one specific heatmap.
3. Use customColor on an individual entry.

• The most productive day
• The longest streak without breaks
• The most active month
• Your average daily intensity

See insights documentation and 8 worked examples.

---

❓ FAQ & troubleshooting

Work through these in order:

1. Is Dataview installed and enabled? Heatmap Tracker reads your notes through Dataview. Without it, there's no data to draw.
2. Does the property actually exist in your notes? Property names are case-sensitive. photo-taking and Photo-Taking are different keys.
3. Are your notes in the searched folder? Without path, the plugin falls back to your Daily Notes folder. If your notes live elsewhere, set path explicitly.
4. Is the year right? The heatmap defaults to the current year. If your data is from last year, use the arrows or set year.
5. Check the console. Ctrl+Shift+I (Windows/Linux) or Cmd+Option+I (Mac) opens devtools — a missing property parameter logs a warning there.

JavaScript queries are off by default. Enable Dataview → Settings → Enable JavaScript Queries, then reload the note.

This is almost always a timezone issue with how dates are parsed. Use plain YYYY-MM-DD strings for date rather than JavaScript Date objects or full ISO timestamps with a time component. If you're pulling from page.file.name on daily notes named YYYY-MM-DD.md, you're already doing the right thing.

The plugin renders from the same data on every platform, so a difference almost always means some entries are being dropped on one of them — check the date format against Accepted date formats, and switch to YYYY-MM-DD if you're using anything else.

Historically this was the cause of #29: dates were handed to the JavaScript engine's own parser, which accepts different formats on desktop (Electron/V8) and on iOS (WebKit/JavaScriptCore), so 01-31-2025 worked on a Mac and silently produced an empty heatmap on an iPhone. Dates are now parsed by the plugin itself and behave the same everywhere.

Still different after fixing the format? Please open an issue with your codeblock and the Obsidian version on both devices.

If several notes share a filename, pass an absolute path so there's no ambiguity:

filePath: page.file.path   // not page.file.name

Set disableFileCreation: true on your trackerData.

true counts as 1, so meditated: true gives you a filled square. false counts as 0; combine with intensityConfig.excludeFalsy: true if you want those days treated as untracked rather than as zero.

Yes — pass an array: property: [running, cycling, swimming]. Values are aggregated.

Your values probably fall into a single bucket of the intensity scale. Set intensityConfig.scaleStart and scaleEnd to bracket the range you actually care about — e.g. scaleStart: 30, scaleEnd: 120 for reading minutes.

Yes. The plugin is not desktop-only and works on Obsidian mobile.

No. Everything is computed locally from your notes. There's no account, no sync, no telemetry.

The heatmap-tracker codeblock needs Dataview. But renderHeatmapTracker(container, trackerData) accepts any entries array, so any JavaScript that can build that array works — Dataview is simply the most convenient source.

Still stuck? Open an issue — include your codeblock, a sample note's frontmatter, and your Obsidian and plugin versions.

---

🔍 How it compares

Heatmap Tracker began as a rewrite of the excellent heatmap-calendar-obsidian by Richardsl, and grew from there.

If all you need is a one-year contribution grid from a dataviewjs script, the original is lighter. If you want tracking, statistics, reports and a no-code path, this is the one.

---

🗺️ What's planned

Have an idea? Open an issue — feature requests genuinely shape this project.

---

🛠️ Development

New to the codebase? ARCHITECTURE.md maps how data flows from a codeblock or dataviewjs script through to the rendered heatmap.

git clone https://github.com/mokkiebear/heatmap-tracker.git
cd heatmap-tracker
npm install
npm run dev

npm run dev starts the TS→JS transpiler and copies the generated JS/CSS/manifest into the example vault whenever they change. The hot-reload plugin — already installed in EXAMPLE_VAULT — then reloads Obsidian automatically, so you don't restart after every change.

If hot-reload isn't picking up changes, add an empty .hotreload file to EXAMPLE_VAULT/.obsidian/plugins/heatmap-tracker/.

Useful scripts

Stack: TypeScript · Preact · esbuild · Jest · Zod

Tip: Ctrl+Shift+I opens devtools inside Obsidian.

Further reading: style guide · adding a language · releasing

---

🤝 Contributing

Contributions are welcome and appreciated — code, docs, translations, bug reports, or just telling me how you use it.

• 🐛 Report a bug
• 💡 Request a feature
• 🌍 Add a translation — a single JSON file
• 📖 Improve the docs or the Example Vault
• 🔧 Open a pull request

Read CONTRIBUTING.md before you start, and note that this project ships a Code of Conduct. Security issues go through SECURITY.md.

---

❤️ Support the project

Heatmap Tracker is free and open source, built and maintained in my own time. If it's useful to you, the cheapest way to help is a ⭐ on the repo — it's how other people find the plugin.

 

---

📄 License & credits

Licensed under the Apache License 2.0.

Built by Maksim Rubanau and contributors.

Inspired by heatmap-calendar-obsidian by Richardsl. Powered by Obsidian Dataview.

⬆ Back to top

If Heatmap Tracker helps you keep a streak alive, consider starring the repo.