Skip to content
AtsuraeDownload

Development sign-in

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

Options

Options are settings people can change for your widget in Customize Widgets: 24-hour time, their name, which city to show. You declare them in widget.json; Atsurae builds the controls.

"options": [
{ "key": "use24Hour", "label": "24-hour time", "kind": "toggle", "defaultValue": "true" },
{ "key": "name", "label": "Your name", "kind": "text", "defaultValue": "" },
{ "key": "style", "label": "Style", "kind": "choice", "defaultValue": "full",
"choices": ["full", "compact"], "choiceLabels": ["Full", "Compact"] }
]
Field Required Meaning
key yes The name you use in tokens, visibleWhen and scripts. Letters and numbers, like showDate.
label yes The label next to the control
kind yes toggle, text or choice
defaultValue yes The starting value, always as text
choices for choice The possible values
choiceLabels no What to show for each choice, in the same order. Without it, the values themselves are shown.
Kind Control Values
toggle a switch "true" or "false"
text a text field anything the person types
choice a pop-up menu one of choices

Values are always text, even for toggles: write "defaultValue": "true", not true.

There are three ways to use an option.

1. As a token, in any text:

{ "text": "Hello, {name}" }

2. To show or hide elements, with visibleWhen: "key=value":

{ "text": "{date:EEEE d MMMM}", "visibleWhen": "style=full" },
{ "text": "{date:d/M}", "visibleWhen": "style=compact" }

See Showing and hiding elements.

3. In a script, as context.options.key:

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

Toggles arrive as the strings "true" and "false", so compare them as strings: context.options.showDate === "true".

A few keys also change built-in tokens:

Key Effect
use24Hour "false" makes {time} and {hour} 12-hour, and {ampm} show AM/PM
showSeconds "true" adds seconds to {time} (and updates every second)
text {text} shows it (used by the built-in Custom Text)
systemMode the value "auto" becomes "battery" on Macs with a battery and "system" on others (used by the built-in Battery & System)

Option values are stored with each widget’s placement, next to its position, size and color. They survive restarts, updates to your widget and even removing and reinstalling it, as long as the id stays the same.

If you rename a key, people’s saved values for the old key are ignored and the new key starts at its defaultValue.

  • Keep it short. Two or three options are plenty. Make good defaults instead of many choices.
  • Use choices over free text when there’s a fixed set of answers.
  • Write labels as nouns or short phrases: “24-hour time”, “City”, “Show seconds”.
  • Make the default look finished. Most people never open the options.