JavaScript API

View as Markdown

umbra.js adds one global, window.umbra. This page groups it by what you want to do. The one-table reference is in the SDK reference.

Know your settings

API	Description
`umbra.ready`	Promise that resolves when the host has sent this widget’s settings.
`umbra.options`	This widget’s option values, e.g. `{ city: "Berlin", units: "c" }`.
`umbra.settings`	`{ refreshSeconds, animations, locked, scale, locale, hour12, editMode, paused, energySaver, options }`, plus `accent` and `themeCss`.
`umbra.widget`	`{ id, instance, name }`: the widget (the folder) and this copy.
`umbra.onSettings(fn)`	Called with the new settings whenever the user changes anything.
`umbra.every(fn)`	Calls `fn` once ready, then every `refreshSeconds`. See Page and lifecycle.
`umbra.onTimeChanged(fn)`	Runs when the system clock or time zone changes.

Fetch data

API	Description
`umbra.fetchJson(url)`	`GET` JSON through the host: no CORS issues, 25 s timeout. Rejects unless the URL is HTTPS and its host is in `permissions.hosts`.
`umbra.fetchText(url)`	Like `fetchJson` but resolves the body as a string (up to 2 MB), for Markdown, CSV or HTML.
`umbra.status`	Data freshness (`state`, `lastOk`, `failures`, `ok()`, `failed()`, `onChange()`). See Freshness and offline.

Plain fetch() also works for declared hosts if the server allows CORS; umbra.fetchJson always works.

Save data

const tasks = await umbra.store.get("tasks", []);
tasks.push({ title: "Read chapter 3" });
await umbra.store.set("tasks", tasks);
umbra.store.onChange(async () => render(await umbra.store.get("tasks", [])));

API	Description
`umbra.store.get(key, fallback?)`	The saved value for `key` (any JSON), or `fallback`.
`umbra.store.set(key, value)`	Saves a JSON value. Rejects when the widget’s data would pass 1 MB.
`umbra.store.remove(key)`, `umbra.store.keys()`	Delete a key; list the keys.
`umbra.store.onChange(fn)`	`fn(key)` when the data was changed from outside (`umbractl data`, MCP). `key` is `null` when everything was cleared.

Use options for what the user picks, and umbra.store for what the widget creates. The store is private to the widget, survives restarts and updates, and lives in %APPDATA%\Umbra\data\<id>.json. Don’t use localStorage: every widget shares one origin.

Talk to the user and the system

API	Needs	Description
`umbra.notify({ title, body?, url?, tag?, actions? })`	`permissions.notifications` and the user’s switch	A real Windows toast. Up to 2 `actions`, `tag` replaces an earlier toast, 5 per 10 minutes per widget. A toast `url` must be HTTPS on a declared host.
`umbra.onNotificationAction(fn)`		`fn({ id, tag })` when a toast button is clicked, while the widget is open.
`umbra.media.nowPlaying()`	`media: "read"`	The current Windows media session (`title`, `artist`, `album`, `app`, `status`, `playing`, `art?`…) or `null`.
`umbra.media.control(cmd)`	`media: "control"`	`play`, `pause`, `toggle`, `next`, `previous`. Needs a physical click on the widget in the last 2 s.
`umbra.system()`	`permissions.system`	`cpu.percent`, `memory.{totalBytes,usedBytes,percent}`, `network.{downBytesPerSec,upBytesPerSec}`. Call from `umbra.every`.
`umbra.run(id, params?)`	`permissions.commands`	Runs a declared, user-approved command. See Running local commands.

Format for the user’s locale

API	Description
`umbra.locale`	The user’s Windows region format as a BCP-47 tag (`"de-DE"`). Pass it to `Intl.` and `toLocaleString`.
`umbra.hour12`	`true` when Windows uses a 12-hour clock. Pass it as `hour12`, and let an option override it if you offer one.
`umbra.fmt(n, decimals = 2)`	`7744.06` → `"7,744.06"`, or `"7.744,06"` when Windows is set to German.

Utilities

API	Description
`umbra.rendered()`	Call once the first real frame is drawn; screenshots wait for it.
`umbra.tween(from, to, ms, onFrame)`	Ease-out-cubic number animation; jumps to `to` when motion is off or the window is hidden.
`umbra.openUrl(url)`	Opens an http(s) link in the user’s browser. Links never navigate the widget.
`umbra.requestFocus()`	Ask for the keyboard, only honoured right after a mouse press on the widget.