Widgets
A widget is a block you define yourself, without code: a data source (a web address that returns JSON, an RSS/Atom feed, an iCalendar file or plain text), a refresh interval, inputs that become fields in the block dialog, and a template written in Markdown with placeholders. HomeTab fetches the source, fills the template and shows the result in the notes look, so a widget follows the theme and can use the notes styles (card, sticky note, paper…).
The built-in library is nothing but such definitions: Weather, Sunrise & sunset, Air quality, Earthquakes, Calendar, Public holidays, Rocket launches, Headlines from a feed, Hacker News, Wikipedia today, xkcd, Exchange rates, Crypto prices, Stock quote, Crypto fear & greed, GitHub repository, Quote of the day, Dad joke and Photo of the day, all from sources that need no API key. Open a widget block's settings and unfold Definition to see theirs, change them, or paste one you were given. The text in that field is the widget: copy it to share it. The library lives in widget-library.js; a new entry there is a new widget in the dialog.
A definition
{
"name": "GitHub",
"inputs": {
"repo": { "label": "Repository", "type": "text", "required": true, "hint": "owner/name" }
},
"source": { "url": "https://api.github.com/repos/{repo}", "type": "json" },
"refresh": "1h",
"template": "### [{{full_name}}]({{html_url}})\n⭐ {{stargazers_count | number}} · pushed {{pushed_at | relative}}"
}
| Field | Meaning |
|---|
name | Default title of the block. |
inputs | Fields shown in the block dialog, keyed by name (letters, digits, _, -). Each has a label, a type (text, number, url or select with options), an optional default, hint and required. options are strings or { "value", "label" } objects. |
source | Optional. url with {input} placeholders, type (json, rss, ics, text, or auto to sniff the response), for JSON an optional path to a part of the response (data.items), and for ICS an optional days (how far ahead to look, default 60, a number or an {input}). Without a source the template renders from the inputs, the location and the time alone. |
refresh | How long a fetched response is reused: 5m, 30m (the default), 2h, up to 24h. |
maps | Optional lookup tables for the map filter: { "weather": { "0": "Clear ☀️" } }. |
format | markdown (the default) or html, see HTML templates below. |
template | Markdown or HTML with placeholders, see below. |
The address may also use {today.year}, {today.month}, {today.day} (two digits) and {today.date} (YYYY-MM-DD) for APIs that take the date in the URL, as the Wikipedia widget does; the cache then rolls over at midnight.
A default may refer to the location the block sits in: {location.lat}, {location.lng} and {location.name}. That is how the Weather widget follows the location's position; when the location has none and the field is empty, the block says so instead of calling the API.
Values typed into inputs are URL-encoded when inserted into source.url, except that slashes are kept (so owner/name works in a path) and an input of type url is inserted as it is. The whole address may come from a url input: "url": "{url}".
What the source gives the template
- json: the parsed response, or the part under
path. - rss:
title, site, and items, each with url, title, date (epoch ms), image, summary. Several feeds are not merged; use a feed block for that. - ics:
name and events (from yesterday to source.days ahead, 60 by default, recurring events expanded, soonest first, at most 500), each with title, start, end (epoch ms), allDay, location, description, url. - text:
{ "text": "the whole response" }.
Besides the data, every template can use inputs.<name>, location.name, location.lat, location.lng and now. Inside a loop, write page.location.name (items often have a location of their own); inputs, now and data (the whole response) work everywhere.
The template language
{{ path }} a value; dotted paths reach into objects and arrays: items.0.title
{{ path | filter | filter:arg }} filters, applied left to right
{{#each list}} … {{else}} … {{/each}} repeat for every item; {{this}}, {{@index}}, {{@number}}, {{@first}}, {{@last}}
{{#if value}} … {{else}} … {{/if}} empty strings, 0, false, empty lists and missing values count as false
{{#unless value}} … {{/unless}}
A block tag alone on its line leaves no empty line behind, so a loop can be laid out one line per item. Single newlines are line breaks, a blank line starts a new paragraph, and the rest is the Markdown the notes block understands: headings, lists, task lists, quotes, code, bold, links, images.
Values from the data are inserted with Markdown characters escaped, so a title with an asterisk or brackets shows as text. A bare URL is left alone (and autolinks), and | raw inserts a value unescaped when a source is trusted to return Markdown.
Filter arguments are numbers, "quoted strings" or bare words (map:weather, date:relday); a dotted name is a path (first:inputs.count).
Filters
| Filter | Does |
|---|
round, round:1 | Round a number (to n decimals, trailing zeros dropped). |
fixed:2 | Fixed decimals. |
number, number:1 | Locale formatting with grouping (2,180). |
date, date:style | Format a date. Styles: short (15 Nov, the default), long, full, weekday, weekday-long, day, month, month-short, year, numeric, iso, relday (Today, Tomorrow, a weekday within the week, else a short date), relweekday (Today, Tomorrow, else the weekday). Accepts ISO strings, YYYY-MM-DD (as a local day), epoch milliseconds or seconds. |
time | Hours and minutes. |
datetime | Short date and time. |
relative | 5 d ago, in 3 h, now. |
duration, duration:min, duration:ms | Seconds (or minutes, milliseconds) as 8 h 15 min. |
plus:n, minus:n, times:n, div:n | Small arithmetic. |
signed:1 | A number with its sign: +1.6. |
change:data.previous | Percentage change from an earlier value, signed: +0.39 %. |
upper, lower, capitalize | Change case. |
truncate:80 | Cut long text with an ellipsis. |
default:"–" | A fallback for empty values. |
plain | Strip HTML tags from a description. |
raw | Insert without escaping. |
first:5, last:3, skip:2, reverse | Slice or reverse a list. |
sort:field | Sort a list by a field (ascending). |
where:field, where:field:value | Keep items whose field is truthy, or equals a value. |
pluck:field | A list of one field from each item. |
join:", " | Join a list into text. |
count | Number of items. |
group:field | Group a list by a field: a list of { key, items }. |
groupday:field | Group by the local day of a date field (groupday:start); key is that day, so `{{key | date:relweekday}}` works. |
spark | A list of numbers as a unicode sparkline (▁▂▃▅█▅▃). |
bar:10, bar:10:max | A percentage (or a value out of max) as a text bar (███████░░░). |
zip | Turn an object of parallel arrays into a list of objects: Open-Meteo's daily { time: [...], temperature_2m_max: [...] } becomes items with time and temperature_2m_max. |
map:name | Look the value up in maps.name; unknown values pass through. |
HTML templates
With "format": "html" the template is HTML instead of Markdown, with the same placeholders, blocks and filters. Data values are inserted HTML-escaped, so a title with angle brackets is text. The output goes through an allowlist before it reaches the page: structural and text tags, lists, tables, images (https addresses, or a file inside the extension such as icons/icon16.png), links (https, http, mailto), class, title, alt, sizes, and a style attribute limited to layout and typography with no url(). Scripts, event handlers, frames, forms, SVG and anything else are dropped; an unknown tag keeps its text. The built-in widgets are HTML templates: open one and unfold Definition to see how they are put together.
A small stylesheet of w- classes is there to build with. They use the theme's colours and the notes styles' paper ink where a card has one.
| Class | Does |
|---|
w-row | A flex row, items centred, wrapping. w-between spreads them out, w-center centres them. |
w-col | A column. |
w-grow | Lets an item take the remaining width. |
w-tiles | A grid of equal tiles, as many across as fit. |
w-tile | One tile: a soft background, centred text. |
w-huge, w-big | A large number or headline (44 px, 22 px). |
w-icon, w-icon-s | An emoji or glyph at 44 px or 22 px. |
w-small, w-muted | Smaller text, muted colour. |
w-badge | A pill. |
w-date | A date badge: <div class="w-date"><b>24</b><small>Dec</small></div>. |
w-day, w-item, w-time | A day row in a list of events, one event line, and its time column. |
w-list | Children separated by hairlines. |
w-spark | Styling for a spark sparkline. |
w-bar | A progress track: <div class="w-bar"><span style="width: {{pct}}%"></span></div>. |
w-divider | A horizontal rule with some air. |
w-cover | On an image: full width, rounded. |
Examples
Weather (Open-Meteo, no key), the Markdown way. The built-in one is the HTML version of this; the coordinates default to the location's position either way.
## {{current.temperature_2m | round}}° {{current.weather_code | map:weather}} {{current.weather_code | map:icons}}
Feels like {{current.apparent_temperature | round}}° · next 24 h {{hourly.temperature_2m | spark}}
{{#each daily | zip}}
**{{time | date:relday}}** {{weather_code | map:icons}} {{temperature_2m_max | round}}° / {{temperature_2m_min | round}}°
{{/each}}
Calendar from an ICS address, the Markdown way (the built-in one groups events by day with a date badge in HTML). Google Calendar: Settings → the calendar → Secret address in iCal format. Apple Calendar: right-click the calendar (or iCloud.com → the calendar's share icon) → Public Calendar, and copy the webcal:// link; only iCloud calendars can be published, not "On My Mac" ones, and anyone with the link can read that calendar. Outlook: Publish calendar → the ICS link. webcal:// addresses are fetched over HTTPS.
{{#each events | first:inputs.count}}
**{{start | date:relday}}**{{#unless allDay}} {{start | time}}{{/unless}} {{title}}{{#if location}} · {{location}}{{/if}}
{{else}}
Nothing coming up.
{{/each}}
One number from a JSON API, with a path into the response:
{
"name": "Bitcoin",
"source": { "url": "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd", "type": "json", "path": "bitcoin" },
"refresh": "10m",
"template": "### ${{usd | number}}\nupdated {{now | time}}"
}
A feed, laid out your way:
{
"name": "xkcd",
"source": { "url": "https://xkcd.com/atom.xml", "type": "rss" },
"refresh": "2h",
"template": "{{#each items | first:1}}**[{{title}}]({{url}})** · {{date | relative}}\n{{/each}}"
}
Good to know
- A widget can only read the address in its definition; nothing else on the page is reachable from a template. Fetched values are inserted as text, and an HTML template goes through the allowlist above before it reaches the page.
- Responses are cached in the browser for the refresh interval and dropped after a day; a block shows the saved data with a "not refreshed" badge when a refresh fails, and "offline" when the browser is.
- The block dialog's Preview fetches and renders without saving, and reports template and JSON errors in place. A saved widget with a problem shows the error inside its block and leaves the rest of the page alone.
- Several blocks reading the same address share one request.
- The built-in widgets are not copied into your settings until you edit their definition; until then they improve with HomeTab updates.
The built-in library
Every widget that ships with HomeTab, with the definition the block dialog shows under Definition. Copy one as a starting point for your own, or to see how a filter or a layout class is used.