Heatmap Tracker

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

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. A three-line codeblock is enough — no JavaScript required.
• 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)
• 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 0.1.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. Run the command Insert Heatmap Tracker from the command palette and fill in the modal — this is the easiest path and writes the codeblock for you.

Or write it by hand:

```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.

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.

[!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.

📖 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

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
}

• Description: Configures how entry values map to colors.

• 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

layout

• Type: "default" | "monthly"
• Default: "default"
• Description: Controls the grid arrangement. "default" renders the traditional GitHub-style week-column grid. "monthly" renders one row per month with days 1–31 as columns — a compact, calendar-style view.
• Example: layout

Date range: monthsToShow, daysToShow, startDate/endDate

These four parameters narrow which dates are displayed instead of the full 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.
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

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.

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.

🗺️ Roadmap

See ROADMAP.md for 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 · i18next · 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.