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. Create the widget
Section titled “1. Create the widget”- Open Atsurae and go to Library.
- 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.
2. Look at the files
Section titled “2. Look at the files”The new folder is called My Widget.atsuraewidget and has two files.
{ "$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] } ]}// 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.
3. Change something
Section titled “3. Change something”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.
4. Make it bigger, and move it
Section titled “4. Make it bigger, and move it”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.
5. Add an element
Section titled “5. Add an element”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.
6. Use the script
Section titled “6. Use the script”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.
7. Let people pick their name
Section titled “7. Let people pick their name”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.
8. When something goes wrong
Section titled “8. When something goes wrong”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.
9. Rename it
Section titled “9. Rename it”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.
Next steps
Section titled “Next steps”- Browse the examples and copy one as a starting point.
- See every live value in the token reference.
- Make it look good on any wallpaper: Readable on any wallpaper.
- Share it: Sharing in the community.
