progress
Dashy vault/Reference/progress
Reference/progress.md

progress: how far along

Properties
code block
progress
keys
8 on the block, 18 on each bar
checked on
Dashy 2.2.0

Bars towards a goal: how far a number has come against a target.

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

From the demo vault

progress
```progress
items:
  - { label: Days logged this year, source: Diary, agg: count, goal: 365, icon: 📔 }
  - { label: Books this year, source: Books, period: year, date_field: finished, agg: count, goal: 24, icon: 📚 }
  - { label: Steps, source: Diary, field: steps, agg: sum, goal: 3000000, unit: steps, sub: three million }
```
renders as
Three progress bars, one past its goal and coloured green

A minimal block

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

progress
```progress
source: Diary
items:
  - { label: Days logged this year, agg: count, period: year, goal: 365 }
  - { label: Running volume, field: distance_km, agg: sum, goal: 200, unit: km }
```

Keys on the block

KeyWhat it doesTypeDefault
columns columns in the grid, 1 to 4; without it every bar is its own row. On a phone a block never shows more than two columns number 1
items required the list of bars list none
sourcealso folder, from folder for every bar that names none of its own; includes nested ones. A bar's own source replaces it text none
tag tag for every bar that names none of its own, with or without the hash. A bar's own tag replaces it text none
where conditions every bar must meet, written like a bar's where. A bar's own where does not replace it but narrows further: both must hold text or list none
period window for every bar that sets none of its own, written like a bar's period. A bar's own period replaces it text or number or map none
date_field date property for every bar that sets none of its own, written like a bar's date_field. A bar's own date_field replaces it text none
date_format date format for every bar that sets none of its own, written like a bar's date_format. A bar's own date_format replaces it text none

Keys on each bar

Each entry under items is one bar.

KeyWhat it doesTypeDefault
label requiredalso title, name caption above the bar text none
goal requiredalso target the target to fill towards; must be above zero; a duration like 8h or 7:30 works too, read as minutes, and a plain number against a field of durations means minutes. usual sets the goal from your own history instead: the average of the bar's value over the 4 periods before its window, like the last 4 months for period: month; { usual: 6 } averages 6. Needs period, on the bar or the block root, one that repeats: not { from, to } number or text or map none
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 numbers are drawn unfiltered text or list none
period narrow to a window: week, month, year (the current calendar one) or a rolling count of days like 30d, 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. The goal is measured against the period's value; notes without a date are left out first. A week starts on the first day of the interface language, Dashy's own when one is picked in its settings, otherwise Obsidian's: Sunday in English, Monday in most European languages; a week named like 2026-W40 is the seven days its name stands for text or number or map none
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. Feeds period's window and the streak, current_streak and latest readings; has no effect on count, sum, avg, min or max without period 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. Steers the same readings date_field does. Month and weekday names (MMMM, dddd) are read in Obsidian's language, or in the Plugin language setting when one is picked text none
fieldalso property, prop numeric frontmatter property, or a checkbox (ticked counts as 1, unticked as 0), dotted for a nested one like health.sleep; required for everything but count, streak and current_streak. A field missing from the whole selection, or holding text rather than a number, shows a dash and a warning naming it; count text instead with where: "field contains ..." and agg: count. A duration string like 5h 58min, 1h30m, 45m, 90 min, 7:30 or ISO 8601 PT1H45M counts as minutes (ISO years and months, like P1M, are not durations; PT1M is a minute), and sum, avg, min, max or latest over a field of durations shows 5h 58m. When every value of the field across the selected notes carries seconds, like 2:16:32 or 2h 16m 32s, the card shows a clock to the second instead: 2:16:32, 0:18:51, and so does the goal. 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 a plain number and warns naming a note of each kind. Also takes a list, like [run_min, bike_min, swim_min], for one number over several properties: each note's value is the sum of the listed properties it holds, a note holding none of them is left out rather than counted as 0, and agg then works on those per-note totals, so avg is the average of the notes' totals and max the biggest one. A list of one is that one field. For streak and current_streak a day is filled when any listed property is, and at_least/at_most compare the day's total. Durations and plain numbers add up as minutes, under the same mixing rule as one field. Each listed property missing from the selection, or holding only text, warns by name, and the others still count; an empty list or an item that is not a property name is an error, and a name listed twice counts once and warns. This differs from a list in the field of a chart series entry or of a heatmap, which pools every single value, so a chart's avg or a heatmap's per_day: avg averages properties rather than notes text or list none
aggalso aggregate count sum avg min max latest streak current_streak text count
at_least with agg: streak or current_streak only: a day counts only once its notes' field values, summed for that day, reach this, like at_least: 5000 steps; combine with at_most for a range. Needs field; ignored on any other aggregate. Takes a duration like 7h or 7:30 too, read as minutes; a plain number against a field of durations means minutes number or text none
at_most with agg: streak or current_streak only: a day counts only while its notes' field values, summed for that day, stay at or under this, like at_most: 5 cigarettes; combine with at_least for a range. Needs field; ignored on any other aggregate. Takes a duration like 7h or 7:30 too, read as minutes; a plain number against a field of durations means minutes number or text none
days with agg: streak or current_streak only: weekdays makes Saturday and Sunday transparent, so they neither break the run nor add to it, whatever they hold; all, the default, counts every day. Ignored on any other aggregate text all
skip_field with agg: streak or current_streak only: 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. A special day neither breaks the run nor adds to it, whatever field holds, the same way days: weekdays treats a weekend, and the two combine. Ignored on any other aggregate text none
unit a suffix after the numbers: km, %, d. Ignored, with a warning, on a value shown as a duration, which carries its own units. The count nouns day, week, month, year, night and time agree with the goal: 3 / 1 day, 10 / 30 days; any other unit stays as written. text none
precision decimal places, 0 to 6; by default a whole number stays whole and a fraction gets one decimal; no effect on a value shown as a duration number none
iconalso emoji emoji text none
sub small caption under the bar text none

How it behaves

  • Going past the goal is shown as it is, 125% stays 125%; only the bar itself stops at full.
  • count over nothing reads a plain 0 and an empty bar; every other aggregate, and streak or current_streak with a field set, shows a dash instead: "no data" and "zero" are different answers.
  • streak counts the longest run of consecutive days on record; label the bar "Best streak" or "Longest streak". current_streak counts the run going on now, label it "Current streak" or "Days in a row": today never breaks it, a day not filled yet leaves the run counted up to yesterday, and only a gap on yesterday or earlier resets it. It counts within the selection after period, where, tag and source, so period: month stops it at the first of the month.
  • period narrows to a calendar week, month, year or a rolling Nd, ending today, or to a fixed window, below. A note's date is its name, as long as it starts with YYYY-MM-DD (2026-03-02 Monday counts, 2026-03-021 does not) or with a date in date_format or in the Daily notes day format, unless date_field names a property instead; a note with no date under either rule is left out before counting.
  • at_least/at_most turn streak into a threshold: a day counts only when its notes' field values, summed for that day, satisfy the bound, at_least: 5000 on steps for example. days: weekdays makes Saturday and Sunday transparent for streak and current_streak: they neither break the run nor extend it, whatever they hold, so a Friday followed by a Monday is a run of two. skip_field does the same for a day any note marks special, vacation: true or sick: flu for example, and combines with days: weekdays. All three keys apply to agg: streak and agg: current_streak only and are ignored on every other aggregate.
  • source, tag, where, period, date_field and date_format written at the block root, next to items:, apply to every bar, so a folder shared by the whole block is written once. A bar's own source, tag, period, date_field or date_format replaces the root's for that bar; where is the exception: the root's conditions and the bar's own both hold. A root folder that does not exist, a root where or period that cannot be read, a blank root source or tag, a root date_field that no note selected under period has a date in, or a root date_format that none of the notes its bars select fits is reported once for the block, not once per bar. A bar's own source: or tag: left empty still replaces the root's, so the bar reads the whole vault or drops the tag filter, and it warns: to inherit the root's value, remove the key. Without items: the block is a single bar and these keys are simply its own.
  • 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.
  • A monthly review: in a note named 2026-10, period: note measures the goal against that month and no other: { label: Running, field: distance_km, agg: sum, goal: 200, unit: km, period: note }. period: 2026-Q4 or period: { from: 2026-09-01, to: 2026-11-30 } names a window outright. 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. current_streak counts back from the window's last day. A window already over does not forgive that day the way a running one forgives today: a closed week with its last day unticked reads 0. A window that has not started yet draws no bars, only the day it starts.
  • One goal over several properties: { label: Training, field: [run_min, bike_min, swim_min], agg: sum, goal: 600, period: month } adds up the three in each note towards the goal, a note with none of them left out.
  • A goal that follows your history: { label: Running, field: run_km, agg: sum, period: month, goal: usual, unit: km } measures this month against the average of the 4 months before it, the same agg, field and selection, and the goal reads usual 48, rounded the way the value is: without precision, a mean of whole counts or sums stays whole. Its tooltip says how many periods it averages. period: week takes the 4 weeks before this one, starting on the first day of the week; 30d the 4 stretches of 30 days before the current one; period: note in 2026-10 or period: 2026-Q4 the 4 months or quarters before the named one; { usual: 2 } the last 2 (up to 120). A period wholly before the first dated note of the selection is skipped, so a vault started in July is not measured against an empty June; after that, a period with nothing in it counts as 0 for count, sum and the streaks and is skipped for avg, min, max and latest. With no period left to average, or an average of 0, the bar shows its value without a goal and a notice says so. Without period it is an error; { from, to } warns, as a span has no periods before it.