Skip to content
AtsuraeDownload

Development sign-in

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

Dates and times

Atsurae has ready-made tokens for the common parts of a date, plus {date:…} for any format you can describe.

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.

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

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

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%.

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.

Also a job for a script; see the Countdown example.