Skip to content
AtsuraeDownload

Development sign-in

Only on a local server with DEV_AUTH. Enter any account name.

Your first widget

In this tutorial you’ll make a widget that greets you and shows the date, then grow it step by step. You’ll learn the parts every widget uses: elements, tokens, fonts, offsets and a small script.

  1. Open Atsurae and go to Library.
  2. In the Widgets section, click Add ▸ New Widget…

Atsurae creates a widget called My Widget, opens its folder in Finder, and opens Customize Widgets with it selected and turned on. You’ll see it in the middle of the preview, and on your desktop.

The new folder is called My Widget.atsuraewidget and has two files.

widget.json
{
"$schema": "https://atsurae.app/docs/schema/widget.schema.json",
"formatVersion": 2,
"id": "my-widget-3f9a2c",
"name": "My Widget",
"summary": "A greeting and today's date.",
"script": { "file": "script.js", "updateEvery": "minute" },
"elements": [
{ "text": "{script.greeting|upper}", "font": { "family": "Michroma", "size": 0.03 }, "tracking": 0.3 },
{ "text": "{weekday}, {monthName} {day}", "font": { "size": 0.016, "weight": "light" }, "opacity": 0.8, "offset": [0, 0.04] }
]
}
script.js
// Runs every minute. Whatever update() returns becomes {script.<name>} tokens.
function update(context) {
const hour = context.now.getHours();
let greeting = "Good evening";
if (hour < 12) greeting = "Good morning";
else if (hour < 18) greeting = "Good afternoon";
return { greeting };
}

Here’s what each part does:

Part Meaning
$schema Lets your editor check the file. Atsurae ignores it.
formatVersion The format the file uses. Always 2 for new widgets.
id A unique ID. Atsurae remembers your widget’s position by it.
name, summary What the Library shows.
script Runs script.js every minute.
elements What to draw, from back to front.

Each element here is text. Words in braces are tokens, replaced by live values: {weekday} becomes “Monday”, {script.greeting} becomes whatever the script returned. |upper makes it uppercase.

Open widget.json in a text editor (which one?), change the second element’s text, and save:

{ "text": "Today is {weekday}", "font": { "size": 0.016, "weight": "light" }, "opacity": 0.8, "offset": [0, 0.04] }

Look at your desktop: the widget already says “Today is Monday”. Atsurae reloads a widget within a second of each save.

Sizes are fractions of the screen height. 0.03 is 3% of the screen’s height. Change the greeting’s font size to 0.06 and save. It doubles.

Positions work the same way. "offset": [0, 0.04] puts the date 4% of the screen height below the widget’s center (positive y goes down). Since you made the greeting bigger, push the date further down:

"offset": [0, 0.06]

The widget as a whole is placed by whoever uses it: drag it around in Customize Widgets. It snaps to the center and to thirds.

Let’s add a thin line between the greeting and the date. Add this element between the two existing ones (don’t forget the comma after the previous element):

{ "type": "shape", "shape": "line", "size": [0.12, 0.002], "opacity": 0.6, "offset": [0, 0.035] },

Elements are text unless they say otherwise. This one has "type": "shape". Shapes, images and progress bars all use size: [width, height], in screen-height fractions too.

Make the greeting personal. In script.js, change the last line:

return { greeting: greeting + ", Sam" };

Save, and the desktop updates. Scripts can return as many values as you like:

const newYear = new Date(context.now.getFullYear() + 1, 0, 1);
return {
greeting: greeting + ", Sam",
daysLeft: Math.ceil((newYear - context.now) / 86400000),
};

Each name you return becomes a token: {script.daysLeft}. The JavaScript guide covers everything a script can read and do.

Hard-coding “Sam” isn’t great if you want to share the widget. Add an option. In widget.json, next to "script":

"options": [
{ "key": "name", "label": "Your name", "kind": "text", "defaultValue": "" }
],

and in script.js:

const name = context.options.name.trim();
return { greeting: name ? `${greeting}, ${name}` : greeting };

Now Customize Widgets shows a Your name field for this widget. See Options.

Make a mistake on purpose: delete a comma and save. The widget’s card in the Library gets a red badge, and Customize Widgets shows the problem under the preview:

The file isn’t valid JSON: …

Put the comma back and the message goes away. Misspelled tokens, missing images and script errors are explained the same way, in the Problems & Console pane, along with anything your script prints with console.log. See Testing and debugging and the full list of errors and warnings.

Give your widget a real name and ID before you share it:

"id": "hello",
"name": "Hello",

You can rename the folder too (keep the .atsuraewidget ending). If you change the id, Atsurae treats it as a new widget, so turn it on and place it again.