Skip to content
AtsuraeDownload

Development sign-in

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

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": [ ... ]
}
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.

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.

Strings in #RRGGBB or #RRGGBBAA form (the # is optional). See Color.

{
"$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 }
]
}