clock widget

The clock widget displays the current time. Every draw tick the engine calls draw() again, so the display stays current at the 50 ms cadence of the held-widget loop — no special mechanism needed.

It reuses the same text-render surface as message and countdown, so font_color, border, and font knobs all work exactly the same way.

clock with format = "%H:%M:%S" and font_color = "rainbow" — the seconds advance because the time is recomputed each draw

Minimal example

[[playlist.section.widget]]
type = "clock"

Options

Option	Type	Default	Description
format	"12h" | "24h" | strftime template	"12h"	Time display format. The presets produce locale-independent output built from datetime fields (not strftime), so they render identically on every platform. A string containing % is passed to strftime verbatim — e.g. "%H:%M" or "%a %b %d %H:%M" for an inline date. Note: %- codes (no-zero-pad) are a Linux-ism and will not work on macOS or Windows.
timezone	IANA name | none	system local	Timezone override, e.g. "America/New_York". Uses stdlib zoneinfo — no extra dependencies. Defaults to the system local timezone.
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_color	RGB list / string / table	[255, 255, 255]	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/.
center	bool	true	Center the time string horizontally. Set to false to left-align.
padding	int	6	Horizontal padding (logical pixels) added at the end when the widget scrolls.

The format knob

Presets

"12h" and "24h" are the built-in presets.

• "12h" — 3:09 PM (no leading zero on the hour; AM/PM suffix)
• "24h" — 15:09 (zero-padded hour)

The presets build the string directly from datetime fields rather than via strftime, so the output is identical on every platform.

Custom strftime format

Any string containing % is passed to Python’s datetime.strftime() verbatim.

[[playlist.section.widget]]
type = "clock"
format = "%H:%M:%S"    # 24-hour with seconds

You can include the date inline in the same format string:

[[playlist.section.widget]]
type = "clock"
format = "%a %b %d  %H:%M"    # e.g. "Sat Jun 13  15:09"

Caution

%- codes (no-zero-pad, e.g. %-I for hour without a leading zero) are a Linux libc extension. Python passes them through to the OS, so they work on the Raspberry Pi but will fail on macOS or Windows. If you author configs on a Mac and deploy to the Pi, test %- codes on the Pi directly.

Timezone

By default the clock shows the system local time. Set timezone to any IANA timezone name to override it:

[[playlist.section.widget]]
type = "clock"
timezone = "America/New_York"
format = "12h"

The timezone is resolved via Python’s stdlib zoneinfo module — no extra dependencies. An invalid timezone name produces a clear validation error at config load.

Common patterns

12-hour clock with a rainbow border

[[playlist.section.widget]]
type = "clock"
format = "12h"
font_color = [255, 255, 255]
border = "rainbow"

24-hour clock with a color cycle

[[playlist.section.widget]]
type = "clock"
format = "24h"
font_color = "color_cycle"

Inline date and time

[[playlist.section.widget]]
type = "clock"
format = "%a %b %d  %H:%M"

This renders a single line like Sat Jun 13 15:09. Stacked date-over-time (two rows) is a planned future addition.

Show the timezone abbreviation

Add %Z to a custom format to print the timezone abbreviation (EDT, JST, …) next to the time:

timezone = "America/New_York", format = "%H:%M %Z"

[[playlist.section.widget]]
type = "clock"
timezone = "America/New_York"
format = "%H:%M %Z"

Caution

%Z and %z are only populated when you set timezone explicitly. The default system-local clock uses a naive timestamp with no timezone info, so %Z/%z render blank — set timezone to label the time with its zone.

Show the UTC offset

%z prints the numeric offset (+0900, -0400) instead of the abbreviation:

timezone = "Asia/Tokyo", format = "%H:%M %z"

[[playlist.section.widget]]
type = "clock"
timezone = "Asia/Tokyo"
format = "%H:%M %z"

To pair the zone label with a 12-hour time, combine the codes: format = "%I:%M %p %Z" renders 05:48 PM EDT.

World clock — one section per city

Give each timezone its own slideshow section to rotate through several cities, each labelled with %Z:

[[playlist.section]]
mode = "slideshow"
hold_time = 5

[[playlist.section.widget]]
type = "clock"
timezone = "America/New_York"
format = "NYC %H:%M %Z"

[[playlist.section]]
mode = "slideshow"
hold_time = 5

[[playlist.section.widget]]
type = "clock"
timezone = "Asia/Tokyo"
format = "TYO %H:%M %Z"

Slideshow mode

The clock widget is designed for slideshow-mode sections, where the engine holds each widget for hold_time seconds and redraws every tick. In a scroll or ticker section the widget will scroll across the panel like any other text widget — which may not be what you want for a clock.

Recommended: slideshow section for a clock

[playlist.section]
mode = "slideshow"
hold_time = 30

[[playlist.section.widget]]
type = "clock"
format = "12h"

Validation

led-ticker validate catches common mistakes before the display starts:

• Unknown preset (format = "12hr") → clock: format '12hr' is not a known preset ('12h'/'24h') or a strftime template (no '%')
• Invalid timezone (timezone = "Mars/Phobos") → clock: timezone 'Mars/Phobos' is not a valid IANA timezone name

See also

• widgets/countdown
• widgets/message
• concepts/color-providers
• concepts/borders