Text and tokens
Text elements are the heart of most widgets. Any text can contain tokens: names in braces that Atsurae replaces with live values.
{ "text": "It's {weekday}, {time}" }shows It’s Monday, 14:05, and keeps it up to date.
A text element
Section titled “A text element”{ "text": "{weekday|upper}", "font": { "family": "Michroma", "size": 0.05, "weight": "regular" }, "tracking": 0.42, "color": "#FFFFFF", "opacity": 0.9}type can be left out: elements are text unless they say otherwise. Only text is required. Without font, text uses the system font at size 0.02. See Fonts and Color.
Tokens
Section titled “Tokens”A token is {name}, optionally with an argument after a colon and a modifier after a bar:
{name}{name:argument}{name|modifier}{name:argument|modifier}Some common ones:
| Token | Example |
|---|---|
{weekday} |
Monday |
{day} {monthShort} {year} |
2 Nov 2026 |
{time} |
14:05 (or 2:05 PM) |
{date:EEEE d MMMM} |
Monday 2 November |
{battery} |
82% |
{track} / {artist} |
the song playing in Music or Spotify |
{weather.temperature} |
21° |
{script.anything} |
whatever your script returns as anything |
{text} |
the value of an option called text |
The token reference lists all of them.
You can mix tokens and plain text freely, and use as many tokens as you like:
{ "text": "CPU {cpu} · MEM {memory}" }Modifiers
Section titled “Modifiers”Add a modifier after | to change a token’s value:
| Modifier | Does | Example |
|---|---|---|
upper |
UPPERCASE | `{weekday |
lower |
lowercase | `{monthName |
percent |
A number from 0 to 1 as a whole percentage | `{year.progress |
round |
A number rounded to a whole number | `{script.temperature |
Only one modifier per token. percent and round leave non-numbers unchanged.
Option tokens
Section titled “Option tokens”Every option is also a token. If your widget has an option with "key": "city", then {city} shows its current value:
"options": [{ "key": "city", "label": "City", "kind": "text", "defaultValue": "Paris" }],"elements": [{ "text": "Hello from {city}" }]Empty values
Section titled “Empty values”Some tokens are sometimes empty: {track} when nothing is playing, {battery} on a Mac without a battery, {weather.*} before the weather has loaded, {script.x} before the script has run. An empty token just disappears from the text.
To hide the whole element when its tokens are empty, add "hideWhenEmpty": true:
{ "text": "♪ {track}", "hideWhenEmpty": true }This hides the element only when every token in it is empty. The plain text (♪ ) doesn’t count. See Showing and hiding elements.
Literal braces
Section titled “Literal braces”Anything between { and the next } is treated as a token. Unknown tokens come out empty, and Atsurae warns about them. Widgets can’t show literal braces in text; use a script value if you really need them.
Text doesn’t wrap
Section titled “Text doesn’t wrap”Each text element is a single line. It grows as wide as it needs to be. For several lines, use several elements with different offsets:
{ "text": "The best way out", "offset": [0, -0.015] },{ "text": "is always through.", "offset": [0, 0.015] }Emoji and symbols
Section titled “Emoji and symbols”Text can contain any Unicode, including emoji (🎉) and symbols (♪ ☀︎ ↑). They’re drawn with the system’s emoji and symbol fonts when your font doesn’t have them. Emoji keep their own colors.
