# `PetalComponents.LocalTime`
[🔗](https://github.com/petalframework/petal_components/blob/v4.15.3/lib/petal_components/local_time.ex#L1)

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

# `local_time`

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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*