Showing and hiding elements
Two fields control whether an element is drawn: visibleWhen for any element, and hideWhenEmpty for text.
visibleWhen with an option
Section titled “visibleWhen with an option”"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 with a token
Section titled “visibleWhen with a token”"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
Section titled “hideWhenEmpty”"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.
What hiding does
Section titled “What hiding does”- 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.
In previews
Section titled “In previews”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.
