Skip to content
AtsuraeDownload

Development sign-in

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

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.

{
"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.

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}" }

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.

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}" }]

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.

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.

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] }

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.