Skip to content
AtsuraeDownload

Development sign-in

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

Showing and hiding elements

Two fields control whether an element is drawn: visibleWhen for any element, and hideWhenEmpty for text.

"visibleWhen": "key=value" draws the element only while the option key has that value:

"options": [
{ "key": "systemMode", "label": "Show", "kind": "choice", "defaultValue": "battery",
"choices": ["battery", "system"], "choiceLabels": ["Battery", "CPU & Memory"] }
],
"elements": [
{ "text": "BATTERY {battery}", "visibleWhen": "systemMode=battery" },
{ "text": "CPU {cpu} · MEM {memory}", "visibleWhen": "systemMode=system" }
]

This works with toggles too ("showDate=true") and text options ("name=" matches an empty name).

"visibleWhen": "{token}" draws the element only while the token has a value. A value counts as off when it’s empty, "false" or "0"; anything else is on.

{ "type": "shape", "size": [0.34, 0.06], "cornerRadius": 0.03, "fill": "#00000066", "visibleWhen": "{track}" }

This background only shows while a song is playing. It’s how the Now Playing Bar hides its pill and icon.

Tokens work with scripts too. Return a boolean, and show elements based on it:

function update(context) {
const hour = context.now.getHours();
return { isDay: hour >= 7 && hour < 19, isNight: hour < 7 || hour >= 19 };
}
{ "type": "image", "src": "images/sun.svg", "size": [0.04, 0.04], "visibleWhen": "{script.isDay}" },
{ "type": "image", "src": "images/moon.svg", "size": [0.04, 0.04], "visibleWhen": "{script.isNight}" }

Booleans arrive as "true"/"false", so false hides the element. You can combine text and tokens, and the element shows when the result isn’t empty: "{track}{artist}" shows if either has a value.

"hideWhenEmpty": true hides a text element while every token in its text is empty:

{ "text": "♪ {track}", "hideWhenEmpty": true }

Plain text in the template doesn’t count, so the ♪ doesn’t keep it visible. It’s shorthand for "visibleWhen": "{track}" on text.

  • A hidden element isn’t drawn and takes no space. Other elements don’t move, because each element is positioned on its own.
  • Hidden elements cost nothing to keep around.
  • If every element is hidden, the widget is invisible, but still turned on.

The Library and Customize Widgets fill empty data with example values (a song title, a battery level, the weather), so elements hidden on the desktop may show in previews. That’s on purpose: it lets people see the whole widget. On the desktop, only real values are used.