Reference/chart.md
chart: a number over time
Properties
code block
chartdashy-chartkeys
18 on the block, 4 on each series
checked on
Dashy 2.2.0
A number over time: a line or bars per day, week, month or year, for one property or a few side by side.
Prefer to have your agent write it? Build a dashboard with an AI agent.
Obsidian Charts turned on?
With Obsidian Charts turned on, Dashy leaves the chart block to it. Write dashy-chart instead: same keys, always Dashy.
From the demo vault
```chart
source: Diary
field: run_km
type: bar
bucket: week
unit: km
goal: 30
```
renders as
A minimal block
The shortest config worth pasting. Change the folder and the property names to yours.
```chart
source: 01-Areas/Personal/Diary
field: sleep_score
agg: avg
```
Keys on the block
sourcetagwheredate_fielddate_formatfieldseriesaggbucketrangetypelabelcolorunitprecisiongoallinktitle| Key | What it does | Type | Default |
|---|---|---|---|
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 chart is drawn unfiltered |
text or list | 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 |
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 |
fieldalso property, prop |
required unless series is set or agg is count, and not allowed together with series. One numeric frontmatter property, or a checkbox (ticked is 1, unticked 0); dotted for a nested one like health.sleep. A duration string like 5h 58min, 7:30 or ISO 8601 PT1H45M counts as minutes, and tooltips, the y axis and the goal's legend entry then read 5h 58m. When every value of the field across the selected notes carries seconds, like 2:16:32, tooltips read as a clock to the second; the axis and the goal's legend entry stay 2h 15m. H:MM is always hours and minutes, so write a 5 km time as 0:18:51, not 18:51; a field mixing durations and plain numbers counts both as minutes, shows plain numbers and warns. One property only: a list here is an error, write series for several lines, or series: [{field: [a, b]}] to fold several properties into one line. A field missing from the selection, holding text rather than a number, or holding numbers only on undated notes errors and says which |
text | none |
series |
several lines, or groups of bars, instead of one field: [{field, agg, label, color}], at most 4. Not used together with the block's own field. Every series is its own line, or its own bar beside the others, never stacked, and all of them share one y axis |
list | none |
aggalso aggregate |
how the values landing in one bucket collapse into one number: sum avg min max count. A bucket's values are every value the field(s) hold on every note dated in it, so two notes on one day both count and avg is over values, not days: the same number a stats card over that week shows. sum of a checkbox is the number of ticked days. count needs no field and counts the dated notes in the bucket; next to a field it warns and ignores it. With series, each entry may override it. An unknown value is an error |
text | sum |
bucket |
day, week, month or year. 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 month starts on the 1st, a year on 1 January. A year is labelled with the year alone, like 2024. Without it, day; with a fixed range such as note, by the window's length: day up to 31 days, week up to 182, month beyond. An unrecognised value warns and falls back the same way |
text | day |
range |
the window: week, month, year (1 January of the current year to today) or a rolling count of days like 90d, 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. Defaults to 30d for day, 182d for week, 365d for month and 3650d for year. The window's start moves back to the start of the bucket it falls in, so only the last bucket can be partial; a fixed window counts only its own days and, once over, has no partial bucket. Above 400 buckets only the most recent 400 are drawn, and a window that as a whole is a single bucket, or shorter than one, is drawn too; both warn. A window still running is judged by its whole length, so this week's note on its first day draws one point and does not warn. An unrecognised value warns and falls back to the default; 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 |
type |
line or bar, for the whole block. Bars always start at zero and hang below it for negative values; a line runs from its data's own minimum to its maximum. An unrecognised value warns and falls back to line |
text | line |
labelalso name |
the single series' name, in the caption and the tooltip; defaults to the field name. With series, each entry carries its own, and this one warns |
text | none |
coloralso colour |
blue green cyan purple pink orange red gray, or #rrggbb. Ignored, with a warning, when series is set: each series carries its own colour instead |
text | blue |
unit |
a suffix in the tooltip, the goal's legend entry and the top y axis label: km, %, steps. Ignored, with a warning, for a series of durations, which carry their own units | text | none |
precision |
decimal places in the tooltip, the goal's legend entry and the y axis labels, 0 to 6; by default a whole number stays whole and a fraction gets one decimal; no effect on durations | number | none |
goalalso target |
a dashed horizontal reference line, its value named in the legend under the chart; the y axis always stretches to show it. A duration like 8h or 7:30 works too, read as minutes, and a plain number against durations means minutes. Anything else warns and is ignored |
number or text | none |
link |
clicking a day bucket opens that day's note, the first by path when there are several. No effect on week, month and year buckets |
true or false | true |
title |
a custom heading instead of the automatic one | text | none |
Keys on each series
Each entry under items (here series) is one series.
| Key | What it does | Type | Default |
|---|---|---|---|
field requiredalso property, prop |
this series' numeric frontmatter property, or a checkbox; dotted for a nested one. A list, like [mood_am, mood_pm], folds several properties into this one series. Durations count as minutes, the same as the block's own field. Not needed with agg: count |
text or list | none |
aggalso aggregate |
this series' own aggregate, overriding the block's agg: sum avg min max count |
text | none |
labelalso title, name |
name shown in the legend and the tooltip. Defaults to the field name(s), or notes for count |
text | 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 series already claimed | text | none |
Keys from other blocks
Written here by habit, these get a message naming the key this block uses instead.
layersisserieshereper_dayisagghereperiodisrangeheretrendisrangehere
How it behaves
- With the Obsidian Charts plugin enabled, write the block as
dashy-chart: Dashy then leaves thechartlanguage to Charts, so achartblock is drawn by Charts.dashy-charttakes the same keys and always works. Turned Charts on while Obsidian was open? Restart Obsidian once. - A note's date is its name, as long as it starts with
YYYY-MM-DDor with a date indate_formator in the Daily notes day format, unlessdate_fieldnames a property instead. Notes without a date are left out, and a selection where none has one warns. Notes dated after today are never drawn. - A week starts on the locale's first day, the same day
period: weekand the heatmap grid use, and a week's tooltip names it:Week of Sun Sep 27, 2026. - A bucket with no data is a gap in the line and no bar, never a zero: a missing day is not a day of zero. An unticked checkbox (
false) is a real 0, andcountover an empty bucket is a plain 0. avgis over values, not days: two notes on one day both count, so a week's average matches a stats card withagg: avgandperiod: week.sumof a checkbox counts the ticked days.- The last bucket is usually still running (this week, this month, this year): it is drawn lighter, or as a hollow point on a line, and its tooltip ends with
so far. - A list in the block's own
fieldis an error rather than a guess: writeseries:for several lines, orseries: [{field: [a, b]}]to fold several properties into one. - Not in this block, on purpose: pie, doughnut, radar and scatter charts, stacked bars, cumulative sums, a second y axis, smoothing and trend lines, zoom, tick and axis settings, annotations, and a height key (the height is the
--dashy-chart-heightCSS variable, which a CSS snippet can change). Steps and sleep on one chart are two chart blocks. - 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, like05-10-2026, is never guessed: without a format it is not a date. range: notecharts the period the note's name stands for: in a weekly note2026-W40,field: stepsandrange: notedraw its seven days. Withoutbucket, a fixed window picks its own:dayup to 31 days,weekup to 182,monthbeyond, so a quarter draws weeks and a year months; a single day is one bucket and warns. The heading names the window,October 2026, instead oflast 30 days. A window already over has noso farbucket, and only its own days count, even in a first week that starts before it. 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 weekgggg-[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, so2026never takes2026-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 window that has not started yet draws no chart, only the day it starts.
Guides that use it
- A weekly chart in Obsidian without Tracker
- A weekly review in Obsidian, without Dataview
- Books per year: a reading log chart in Obsidian
Dashy is in Obsidian's community plugins. Search for Dashy, install, enable, then run Dashy: Insert block and pick chart.