Dates and times
Atsurae has ready-made tokens for the common parts of a date, plus {date:…} for any format you can describe.
Ready-made tokens
Section titled “Ready-made tokens”| Token | Shows | Example |
|---|---|---|
{weekday} |
Day of the week | Monday |
{weekdayShort} |
Short day of the week | Mon |
{day} |
Day of the month | 2 |
{dayPadded} |
Day of the month, two digits | 02 |
{month} |
Month number, two digits | 11 |
{monthName} |
Month name | November |
{monthShort} |
Short month name, without a period | Nov |
{year} |
Year | 2026 |
{time} |
Hours and minutes (see below) | 14:05 or 2:05 PM |
{hour} |
Hour (see below) | 14 or 2 |
{minute} |
Minute, two digits | 05 |
{second} |
Second, two digits | 09 |
{ampm} |
AM or PM, only in 12-hour time | PM |
Names follow the language and region set in System Settings ▸ General ▸ Language & Region, so a French Mac shows lundi and novembre.
12- and 24-hour time
Section titled “12- and 24-hour time”{time}, {hour} and {ampm} follow an option called use24Hour, if your widget has one. Without it they use 24-hour time.
"options": [ { "key": "use24Hour", "label": "24-hour time", "kind": "toggle", "defaultValue": "true" }]use24Hour on (or no option) |
off | |
|---|---|---|
{time} |
14:05 | 2:05 PM |
{hour} |
14 | 2 |
{ampm} |
(empty) | PM |
{time} also follows an option called showSeconds: when it’s "true", {time} shows 14:05:09, and the widget updates every second.
{ "key": "showSeconds", "label": "Show seconds", "kind": "toggle", "defaultValue": "false" }The built-in Time widget uses both options.
Any format: {date:pattern}
Section titled “Any format: {date:pattern}”{date:…} formats the current date with a Unicode date pattern: letters stand for parts of the date, and repeating a letter changes the style.
{ "text": "{date:EEEE, d MMMM}" }→ Monday, 2 November
| Pattern | Means | Example |
|---|---|---|
yyyy |
year | 2026 |
yy |
two-digit year | 26 |
M / MM |
month number | 11 |
MMM |
short month | Nov |
MMMM |
month name | November |
MMMMM |
month initial | N |
d / dd |
day of month | 2 / 02 |
D |
day of year | 306 |
E / EEE |
short weekday | Mon |
EEEE |
weekday | Monday |
EEEEE |
weekday initial | M |
w |
week of year | 45 |
Q / QQQ / QQQQ |
quarter | 4 / Q4 / 4th quarter |
H / HH |
hour, 0–23 | 14 |
h / hh |
hour, 1–12 | 2 / 02 |
m / mm |
minute | 5 / 05 |
s / ss |
second | 9 / 09 |
a |
AM / PM | PM |
z / zzzz |
time zone | PST / Pacific Standard Time |
'text' |
literal text | 'Week' w → Week 45 |
Examples:
| Token | Shows |
|---|---|
{date:yyyy-MM-dd} |
2026-11-02 |
{date:d.M.yyyy} |
2.11.2026 |
{date:EEE d MMM} |
Mon 2 Nov |
{date:'Week' w} |
Week 45 |
{date:HH:mm:ss} |
14:05:09 |
{date:h:mm a} |
2:05 PM |
{date:QQQQ} |
4th quarter |
A pattern that contains s makes the widget update every second; others update every minute.
{date} with no pattern shows yyyy-MM-dd. Colons inside the pattern are fine: everything after the first colon is the pattern.
Progress through time
Section titled “Progress through time”These tokens give how far through the current period it is, as a number from 0 to 1, for progress bars:
| Token | Example at 14:00 on 2 November |
|---|---|
{day.progress} |
0.5833 |
{week.progress} |
depends on your first weekday |
{month.progress} |
0.05278 |
{year.progress} |
0.8372 |
Show them as percentages with |percent: {year.progress|percent} → 84%.
Other time zones
Section titled “Other time zones”Tokens always use the Mac’s time zone. For other cities, use a script with JavaScript’s Intl date formatting:
function update(context) { return { tokyo: context.now.toLocaleTimeString("en-US", { timeZone: "Asia/Tokyo", hour: "2-digit", minute: "2-digit", hour12: false, }), };}The World Clock example does this for three cities.
Countdowns and dates relative to today
Section titled “Countdowns and dates relative to today”Also a job for a script; see the Countdown example.
