countdown widget

The countdown widget is a message with date arithmetic baked in. Every draw it renders <text>: <N> where N is the number of days from today to countdown_date. The count is recomputed on each draw, so it rolls to the next value at midnight without restarting the process.

Once countdown_date has passed, the widget drops out of the rotation. To count up from a past date instead, see countup.

countdown to 2026-06-21 with rainbow font

Minimal example

[[playlist.section.widget]]
type = "countdown"
text = "Until Summer"
countdown_date = 2026-06-21

Options

Option	Type	Default	Description
`text`	string	required	Label shown before the day count, e.g. `"Until Summer"` renders as `"Until Summer: 42"`.
`countdown_date`	date	required	Target date in TOML date syntax: `2026-12-25`. The day count is recomputed on every draw so the value updates at midnight without restarting the process.
`font`	string	`"6x12"`	BDF font name (e.g., `"5x8"`, `"6x12"`) or hires font (e.g., `"Inter-Bold"`).
`font_size`	int	(BDF cell height)	Real-pixel font size for hires fonts. Required if `font` is a hires font name.
`font_threshold`	int 0–255	`128`	Rasterization threshold for hires fonts. Lower = thicker glyphs.
`font_color`	RGB list / string / table	`[255, 255, 0]`	Constant `[r,g,b]`, `"rainbow"`, `"color_cycle"`, `"random"`, or `{style="gradient", from=[...], to=[...]}`.
`bg_color`	RGB list	none	Background fill color. Painted across the full panel before text.
`border`	`"rainbow"` \| `"color_cycle"` \| `"lightbulbs"` \| `[r,g,b]` \| `{style="...", ...}`	none	Perimeter border ring — five styles (rainbow chase, color cycle, constant, bands, lightbulbs); see /concepts/borders/.
`padding`	int	`6`	Horizontal padding (logical pixels) added when text scrolls.
`timezone`	IANA name \| none	system local	Timezone for computing the day count and the show/hide boundary, e.g. `"America/New_York"`. Uses stdlib `zoneinfo` — no extra dependencies. Defaults to the sign's local date.

Set the content string with text =.

Common patterns

Branded color

constant `font_color` paints the count and label in the same RGB

[[playlist.section.widget]]
type = "countdown"
text = "Until the Show"
countdown_date = 2026-09-01
font_color = [255, 140, 0]

Rainbow sweep

rainbow per-character sweep across the full text + count

[[playlist.section.widget]]
type = "countdown"
text = "Days Left"
countdown_date = 2026-12-31
font_color = "rainbow"

Rainbow border with solid text

animated rainbow chase around the panel perimeter, white text inside

[[playlist.section.widget]]
type = "countdown"
text = "Until Launch"
countdown_date = 2026-11-15
font_color = [255, 255, 255]
border = "rainbow"

Tips

Typewriter is not available on `countdown`

animation = "typewriter" is rejected on countdown — it’s only supported on message, gif, and image. For dynamic color, use font_color = "rainbow" or a gradient.