PetalComponents.LocalTime (petal_components v4.8.0)

Copy Markdown View Source

Timestamps rendered in the visitor's own timezone, language and calendar - no server timezone tables, no JavaScript date library. The server renders a semantic <time datetime="..."> carrying the UTC instant; the PetalLocalTime hook formats it client-side with the browser's Intl.

<.local_time id="t1" at={@message.inserted_at} />
<.local_time id="t2" at={@message.inserted_at} format="relative" />
<.local_time id="t3" at={@dt} format={%{dateStyle: "full"}} />

Formats

  • "datetime" (default) - medium date + short time, e.g. "21 Jul 2026, 8:41 pm"
  • "date" / "time" - one half only
  • "relative" - "12 seconds ago", "yesterday", "in 3 weeks" (Intl.RelativeTimeFormat, numeric auto). Ticks live on a decaying cadence (5s while under a minute old, 30s under an hour, then 15min/1h), re-renders when a background tab wakes (browsers throttle hidden timers), and flips to the absolute form once older than threshold. Hover shows the full absolute time via title.
  • a map - raw Intl.DateTimeFormat options with camelCase keys, passed through as-is: %{weekday: "long", hour: "2-digit", minute: "2-digit"}.

Before the hook runs - and anywhere JavaScript never runs (RSS scrapes, reader modes, tests) - the element shows the UTC ISO string: honest, sortable, machine- and human-readable.

at accepts a DateTime (any zone - normalised to UTC without needing a timezone database), a NaiveDateTime (assumed UTC), or an ISO8601 string (passed through untouched).

Summary

Functions

local_time(assigns)

Renders a localised <time> element bound to the PetalLocalTime hook.

Functions

local_time(assigns)

Renders a localised <time> element bound to the PetalLocalTime hook.

Attributes

  • id (:string) (required)
  • at (:any) (required) - DateTime (any zone), NaiveDateTime (assumed UTC), or ISO8601 string.
  • format (:any) - "datetime", "date", "time", "relative", or a map of Intl.DateTimeFormat options (camelCase keys). Defaults to "datetime".
  • locale (:string) - BCP 47 tag, e.g. "de-DE"; defaults to the browser's own. Defaults to nil.
  • timezone (:string) - IANA zone, e.g. "Australia/Sydney"; defaults to the browser's own. Defaults to nil.
  • threshold (:integer) - relative format only: age in seconds beyond which the absolute form renders instead (default 7 days). Defaults to 604800.
  • title (:boolean) - relative format only: show the absolute time on hover. Defaults to true.
  • class (:any) - Defaults to nil.
  • Global attributes are accepted.