widget.json
A widget is defined by one JSON object, in a .json file or in widget.json inside a package.
{ "$schema": "https://atsurae.app/docs/schema/widget.schema.json", "formatVersion": 2, "id": "world-clock", "name": "World Clock", "summary": "The time in three cities.", "author": "Sam", "version": "1.0", "options": [ ... ], "script": { "file": "script.js", "updateEvery": "minute" }, "elements": [ ... ]}Fields
Section titled “Fields”| Field | Type | Required | Default | Description |
|---|---|---|---|---|
$schema |
string | no | The JSON Schema URL, for editor autocomplete. Ignored by Atsurae. | |
formatVersion |
integer | yes | The format version. Use 2. |
|
id |
string | yes | Unique ID: lowercase letters, numbers and dashes, starting with a letter or number (^[a-z0-9][a-z0-9-]*$). |
|
name |
string | yes | The name shown in Atsurae. Can’t be empty. | |
summary |
string | no | One sentence shown in the Library. | |
author |
string | no | Who made it. | |
version |
string | no | Your version label. Not used by Atsurae. | |
options |
array of options | no | [] |
Settings people can change. |
script |
script | no | JavaScript that provides {script.*} tokens. |
|
elements |
array of elements | yes | What to draw, back to front. At least one. |
Unknown fields are ignored with a warning, so a typo like "elemnts" is easy to spot.
script
Section titled “script”| Field | Type | Required | Default | Description |
|---|---|---|---|---|
file |
string | yes | The script’s path inside the package, e.g. "script.js" |
|
updateEvery |
"minute", "second" or number |
no | "minute" |
How often update runs. Numbers are seconds, at least 1. |
A widget with a script must be a package (.atsuraewidget folder) containing the file. See the Script API.
All sizes and distances (font.size, size, offset, cornerRadius, strokeWidth, lineWidth) are fractions of the screen height. tracking is in ems. See Position and size.
Colors
Section titled “Colors”Strings in #RRGGBB or #RRGGBBAA form (the # is optional). See Color.
A complete example
Section titled “A complete example”{ "$schema": "https://atsurae.app/docs/schema/widget.schema.json", "formatVersion": 2, "id": "battery-ring", "name": "Battery Ring", "summary": "Battery level as a ring, with charging state.", "author": "Atsurae", "version": "1.0", "elements": [ { "type": "progress", "style": "ring", "value": "{battery.level}", "size": [0.09, 0.09], "lineWidth": 0.007, "color": "#7CFFB2", "track": "#FFFFFF30" }, { "text": "{battery}", "font": { "size": 0.02, "weight": "semibold" } }, { "text": "{batteryState|upper}", "font": { "family": "Michroma", "size": 0.009 }, "tracking": 0.2, "opacity": 0.75, "offset": [0, 0.065], "hideWhenEmpty": true } ]}