Heatmap Tracker

Heatmap Tracker plugin for Obsidian

The Heatmap Tracker plugin for Obsidian is a powerful and customizable tool designed to help you track, visualize, and analyze data over a calendar year. Perfect for habit tracking, project management, personal development, or any kind of data visualization, this plugin enables you to create beautiful, interactive heatmaps directly within Obsidian. Whether you’re monitoring progress, visualizing trends, or staying on top of daily goals, the Heatmap Tracker enhances your productivity and organization. Discover its intuitive features, flexible customization options, and seamless integration with Obsidian in the detailed guide below.

Tip: Check Example Vault. There're lots of good examples (and I update it often).

Prerequisites

This plugin requires the Obsidian Dataview plugin to be installed and enabled to automatically fetch data from your notes.

Getting Started

1. Install Dataview: Ensure the Dataview plugin is active in your Obsidian vault.
2. Add Data to Daily Notes: Add a frontmatter property to your daily notes (e.g., YYYY-MM-DD.md) that you want to track.
   • Numeric: photo-taking: 10
   • Boolean: photo-taking: true (counts as 1)
3. Insert Heatmap: Use the command Insert Heatmap Tracker to generate a heatmap through the interactive modal.

Basic Usage

This plugin comes with frontmatter tracking out of the box. You can use the heatmap-tracker codeblock with the following parameters:

```heatmap-tracker
property: <frontmatter_property_key>
```

This will look for frontmatter_property_key in your daily notes and activate a spot on the heatmap wherever that property is set.

You can also use an array of property names as such:

```heatmap-tracker
property: [<frontmatter_property_key_1>, <frontmatter_property_key_2>, ...]
```

This will aggregate the values of all specified properties on the heatmap.

Basic Usage 2.0

You can add a heatmap tracker using command: Insert Heatmap Tracker. This is the easiest way to get started.

Advanced Usage

If you want something more involved, you may use a dataviewjs codeblock as such (update trackerData with your own dataset to visualize custom data points):

// 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 (for cases when you have multiple notes with the same 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);

Notes

• If you provide filePath for each entry (page.file.path), clicking a heatmap box opens that exact file. If the file is missing, the plugin offers to create it at the same path.
• If filePath is not set on a box but trackerData.basePath is provided, the plugin proposes creating/opening trackerData.basePath/YYYY-MM-DD.md.
• If neither is available, it falls back to the Daily Notes settings (folder/format) via the Daily Notes API.

Tracker Settings Documentation

You can also read about parameters in EXAMPLE_VAULT (there're examples).

year

• Type: number
• Default: Current year (new Date().getFullYear())
• Description: Specifies the year for which the heatmap should display data by default.

colorScheme

• Type: object
• Default:

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

• Description: Defines the color scale used for representing different intensity levels in the heatmap. Each color corresponds to a specific range of data intensity.

customColor

• Type: string
• Default: undefined
• Description: Entry property. Sets the color for specific entry. If you want some entry (based on the condition) to have a different color, you can set it here.

entries

• Type: array
• Default:

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

• Description: A list of data entries for the heatmap. Each entry includes:
  • date: The date of the entry (ISO string format).
  • customColor: The color for that entry.
  • intensity: The data intensity for that date.
  • content: Optional tooltip or note associated with the date.

showCurrentDayBorder

• Type: boolean
• Default: true
• Description: Indicates whether the current day should be highlighted with a border on the heatmap.

defaultEntryIntensity

• Type: number
• Default: 4
• Description: The default intensity assigned to new data entries if no intensity is explicitly specified.

intensityScaleStart

• Type: number
• Default: 1
• Description: The minimum value for the intensity scale. Used to determine the color mapping for the lowest intensity values in the heatmap.

intensityScaleEnd

• Type: number
• Default: 5
• Description: The maximum value for the intensity scale. Represents the highest possible intensity that can be mapped to the color scale.

excludeFalsy

• Type: boolean
• Default: undefined (falsy values are included)
• Description: When set to true, entries with falsy intensity values (0, undefined, null, false) will be excluded from the heatmap.

basePath

• Type: string
• Default: undefined
• Description: Base folder used to collect entries. If set, the plugin will propose creating new files in this folder when clicking on empty heatmap boxes.

separateMonths

• Type: boolean
• Default: true
• Description: Determines whether months should be visually separated within the heatmap layout.

insights

• Type: array
• Default: []
• Description: Powerful property for calculating and displaying your own insights in Statistics. Check this example.

layout

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

monthsToShow

• Type: number
• Default: undefined (shows full year)
• Description: Show the current month plus the N previous months. For example, monthsToShow: 3 displays 4 rows (current month + 3 prior). Takes precedence over daysToShow and startDate/endDate. Best used with layout: "monthly".

daysToShow

• Type: number
• Default: undefined (shows full year)
• Description: Show the last N days from today. Takes precedence over startDate/endDate but is overridden by monthsToShow.

startDate

• Type: string (format: YYYY-MM-DD)
• Default: undefined
• Description: First date to display. Must be used together with endDate. Overridden by daysToShow or monthsToShow.

endDate

• Type: string (format: YYYY-MM-DD)
• Default: undefined
• Description: Last date to display. Must be used together with startDate. Overridden by daysToShow or monthsToShow.

To be used with Obsidian Dataview, but could be used standalone or with other plugins as well (if you know some javascript).

📦 Plugin Features

Roadmap

📍 Check out the Roadmap to see what's planned for the future!

Development (Windows/Mac):

npm run dev - will start an automatic TS to JS transpiler and automatically copy the generated JS/CSS/manifest files to the example vault when modified (Remember to run npm install first).

After the files have been transpiled, the hot-reload plugin (https://github.com/pjeby/hot-reload) then reloads Obsidian automatically. Hot-reload is installed in the example vault by default. its used to avoid restarting obsidian after every change to code.
(remember to add an empty .hotreload file to "EXAMPLE_VAULT/.obsidian/plugins/heatmap-tracker/" if not already present, as this tells hot-reload to watch for changes)

npm run build generates the files ready for distribution.

Tip: ctrl-shift-i opens the devtools inside Obsidian.

Inspired by:

https://github.com/Richardsl/heatmap-calendar-obsidian