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"] }]Fields
Section titled “Fields”| 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.
Using option values
Section titled “Using option values”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".
Keys with special meaning
Section titled “Keys with special meaning”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) |
Per placement
Section titled “Per placement”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.
Good options
Section titled “Good options”- 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.
