heatmap
Dashy vault/Reference/heatmap
Reference/heatmap.md

heatmap: the year

Properties
code block
heatmap
keys
16 on the block, 3 on each layer
checked on
Dashy 2.2.0

A year by days, or a month as a calendar: one cell per day, coloured by a number from frontmatter.

Prefer to have your agent write it? Build a dashboard with an AI agent.

From the demo vault

heatmap
```heatmap
source: Diary
field: sleep_score
color: purple
bands: [90, 80, 70]
title: Sleep, last twelve months
```
renders as
A year of days coloured by sleep score, with a legend

A minimal block

The shortest config worth pasting. Change the folder and the property names to yours.

heatmap
```heatmap
source: 01-Areas/Personal/Diary
field: sleep_score
color: purple
bands: [90, 80, 60]
```

Keys on the block

KeyWhat it doesTypeDefault
sourcealso folder, from folder; includes nested ones text none
tag tag, with or without the hash text none
where a condition like year = 2026, rating >= 4, tags contains books, or several that must all hold: joined with and (year = 2026 and rating >= 4) or written as a list ([year = 2026, "rating >= 4"]). The field name may be a dotted path into a nested property, like health.sleep > 70. date empty keeps the notes where a property is missing, blank or an empty list, and date not empty the notes where it holds a value, 0 and an unticked checkbox included. or is not supported; quote a value holding the word and or or. One unreadable condition drops the whole filter with a warning, and the grid is drawn unfiltered text or list none
fieldalso property, prop required unless layers is set, and not allowed together with it: exactly one of the two. A numeric frontmatter property, or a checkbox: ticked days are painted, unticked stay empty; dotted for a nested one like health.sleep. Also takes a list, like [mood_am, mood_pm], to collapse several properties from the same note into one day with per_day. A list of checkboxes, like [gym, read], counts the ticked ones, a box missing from a note counting as unticked: with two, a day with both is full colour and a day with one is paler. A number in any of them turns the count off and warns. A field missing from the selection, or holding text rather than a number, errors and says which; count text elsewhere with a stats card's where: "field contains ..." and agg: count. A duration string like 5h 58min, 7:30 or ISO 8601 PT1H45M counts as minutes, and tooltips, the caption's average and the legend then read 5h 58m. When every value of the field across the selected notes carries seconds, like 2:16:32, tooltips and the average read as a clock to the second; the legend stays 2h 15m. H:MM is always hours and minutes, never a time of day or minutes and seconds: a 5 km time written 18:51 reads as 18 hours, so write race times as 0:18:51. A field mixing durations and plain numbers counts both as minutes, shows plain numbers and warns text or list none
per_day how several values landing on one day combine: sum, avg or max. Several values happen either from two or more notes on the same day, or from a field list on one note, or both at once. An unrecognised value warns and falls back to sum. With layers, it applies to each layer's own field(s) separately text sum
date_field a date frontmatter property to read instead of the note name: 2026-03-02 or 2026-03-02T10:30, or in date_format, or a dotted path into a nested property like meta.date text none
date_format a date format for note names and date_field values not written as YYYY-MM-DD, in moment notation: DD.MM.YYYY, MM/DD/YYYY, YYYYMMDD. Tried after YYYY-MM-DD and before the day format of the Daily notes or Periodic Notes settings, which is read without this key. A name or a value only has to start with the date (05.10.2026 Monday and 05.10.2026 14:30 count); the match is strict, so 5.10.2026 and 31.02.2026 are no date under DD.MM.YYYY. Needs a year, a month and a day, and warns when no selected note fits it. Month and weekday names (MMMM, dddd) are read in Obsidian's language, or in the Plugin language setting when one is picked text none
skip_field a property marking a day special, like vacation: true or sick: flu; a day is special once any note landing on it sets the property to anything other than false, a blank string, 0 or absent. Its cell gets a hatched overlay, on top of its painted colour when it has one. Works with layers too text none
coloralso colour blue green cyan purple pink orange red gray, or #rrggbb. Ignored, with a warning, when layers is set: each layer carries its own colour instead text blue
layers several activities on one grid, each in its own colour, instead of one field: [{field, color, label}]. Not used together with the block's own field. The first layer painted on a day colours that cell and supplies its value and link, or with pick: max the one with the largest value that day; the tooltip lists every layer with a value that day, in list order. The caption then counts days where any layer painted and drops the average, since averaging different fields together says nothing useful list none
pick with layers, which layer wins a day several of them painted: first (the first in list order) or max (the largest value that day, after that layer's own per_day; a ticked checkbox counts as 1, a duration as minutes; a tie goes to the first in list order). The winner colours the cell and supplies its link and the value that shading and bands read; the tooltip still lists every layer with a value that day. Comparing different fields only makes sense when they share a unit, minutes against minutes for example. An unrecognised value warns and falls back to first; without layers it warns and is ignored text first
bands thresholds from the top down: [90, 80, 60] or [{min, alpha, label}]; anything below the lowest falls into the bottom band. Without bands, each grid (a calendar year, or the one range window) shades itself by its own minimum and maximum: a single checkbox field or a grid where every painted value is the same still paints one flat colour instead. A list of checkboxes is shaded by how many are ticked, with all of them ticked as the top even before any day reaches it; with per_day: avg by the share of the listed boxes ticked, and with per_day: max it stays flat. Two notes on the same day add their ticks up, so such a day can go past the top. A threshold may be a duration, [8h, 7h] or {min: 7h}, read as minutes; a plain number against a field of durations means minutes, and the legend reads as durations list none
range one grid over a window instead of a grid per calendar year: week, month, year (1 January of the current year to today) or a rolling count of days like 365d, all ending today; note, the day, week, month, quarter or year the name of the note this block sits in stands for, like 2026-W40; a period written out the same way: 2026-10-01, 2026-W40, 2026-10, 2026-Q4 or 2026; or { from: 2026-09-01, to: 2026-09-30 }, both days included, from alone running to today. Columns still align to the week the same way, a named week starting on its own first day; a fixed window's caption starts with its name, like Sep 28, 2026 to Oct 4, 2026; a day outside the window is neither drawn nor counted. With layout: calendar, a month or a week draws the whole month or week as a calendar instead. A window that has not started yet draws no grid, only the day it starts. An unrecognised value warns and falls back to a grid per year; note in a note not named for a period, and a from/to that does not read, are errors text or number or map none
layout grid (the default) or calendar. calendar works with a window of one month or one week only: range: month or range: week for the current one, or a fixed one such as range: 2026-10, range: 2026-W40, range: note in a monthly or weekly note, or a from/to of a whole month or of seven days starting on the locale's first day of the week; it draws that whole month (1st to last day) or week as a calendar: weekday columns starting on the locale's first day of the week, the month name and year above (both months for a week that crosses into the next), each day its number with dots under it. Without layers, one dot per note that painted that day, at most 3; with layers, one dot per layer painted that day in its colour, in list order, at most 4, whatever pick says. Days after today are dimmed, with no dots; a month or week already over has none. Tooltips, links, today's ring, skip_field hatching and the caption work as on the grid. bands has nothing to shade there and is ignored with a warning. With any other range, or none, calendar warns and the grid is drawn; an unrecognised value warns and falls back to grid text grid
title a custom heading instead of the automatic one text none

Keys on each layer

Each entry under items (here layers) is one layer.

KeyWhat it doesTypeDefault
field requiredalso property, prop this layer's own numeric frontmatter property, or a checkbox; dotted for a nested one, or a list to collapse several properties into this layer's day. Same shapes as the block's own field, durations included text or list none
coloralso colour blue green cyan purple pink orange red gray, or #rrggbb. Without one, the next free colour from the palette, skipping colours other layers already claimed text none
labelalso title, name name shown in the legend and the cell tooltip. Defaults to the field name(s) text none

How it behaves

  • A note's date is its name, as long as it starts with YYYY-MM-DD (2026-01-05 Monday counts, 2026-01-051 does not) or with a date in date_format or in the Daily notes day format, unless date_field names a property instead. That is how the block knows which cell it belongs to.
  • Two or more notes landing on the same day paint one cell, and so does a field list on one note: per_day (default sum) says how the day's values combine, and a ticked or numeric contributor always outweighs a false one on the same day.
  • Years are taken from the data, newest first, but never one later than today: a note dated in the future draws nothing extra and counts nowhere in the grid. If every dated note turns out to be in the future, the current year is still drawn, empty.
  • layers replaces field for tracking several activities on one grid, each its own colour: layers: [{field: gym, color: blue}, {field: run, color: green, label: Running}]. When two layers land on the same day, the first one in the list colours the cell, or with pick: max the one with the larger value; the tooltip still lists every layer that has a value that day. Minutes per sport, coloured by the sport that took the longest: layers: [{field: run_min, color: green, label: Running}, {field: bike_min, color: blue, label: Cycling}] with pick: max. Compare layers in the same unit only.
  • skip_field marks special days, vacation or sick for example: they still show a hatched cell, keeping any painted colour underneath, and their count in the caption is unchanged (a special day with no value is still not present).
  • range draws one grid over a window ending today instead of a grid per year: range: 365d is a rolling year that crosses 1 January in a single grid rather than splitting into two. Everything else works the same over that one grid: bands, layers, skip_field and its legend row, the caption's count and average, tooltips and links.
  • layout: calendar with range: month draws a month calendar of a habit inside the note: range: month, layout: calendar and field: gym, or a few layers. Each day shows its number and a dot per note or layer that painted it; the days still ahead are dimmed.
  • Daily notes named another way, like 05.10.2026, are read in the day format set in the Daily notes or Periodic Notes settings, with no key at all. Without that setting, name the format: date_format: DD.MM.YYYY. A time after the date is fine (2026-10-05-14:30), but an order that could be read two ways, like 05-10-2026, is never guessed: without a format it is not a date.
  • range: note draws the period the note's name stands for: in a note named 2026-10, range: note, layout: calendar and field: gym draw October as a calendar, and in 2026-W40 the same keys draw that week. range: 2026 draws a year, range: { from: 2026-06-01, to: 2026-08-31 } a summer. The name is read in the formats set in Periodic Notes for each period (one switched on there with no format saved, in the plugin's default, so a week is the locale week gggg-[W]ww), the day falling back to Daily notes, then as ISO: YYYY-MM-DD, GGGG-[W]WW, YYYY-MM, YYYY-[Q]Q, YYYY, the day first, so 2026 never takes 2026-10. A note named otherwise is an error that lists those formats; nothing is guessed. In a template, a note in the template folder of the core Templates plugin or of Templater, a name that is no period is no error: the block draws no numbers but a line saying the note is a template, under any other problem the config has, and a note made from it and named for a period counts that period. A week named like 2026-W40 starts on its own first day, whatever the interface language says. A window that has not started yet draws no grid, only the day it starts.