09 · Workflow

Timer

direction up · down × variant ring · mini × size sm/md/lg × color (7) × format auto/hms/hm

A stopwatch or countdown, as a ring or compact.

Counting down and up

02:14:08
.heex
<div class="flex flex-wrap items-center gap-2.5">
  <.timer id="timer-live-down" demo direction="down" total={600} elapsed={0} color="primary" />
  <.timer id="timer-live-up" demo direction="up" total={28800} elapsed={0} color="secondary" />
  <.timer id="timer-live-mini" variant="mini" demo total={28800} elapsed={8048} format="hms" label="Shift time" />
</div>

size × color

04:20
04:20
04:20
05:00
05:00
05:00
05:00
05:00
05:00
05:00
.heex
<div class="flex flex-col gap-3">
  <div class="flex flex-wrap items-center gap-2.5">
    <.timer id="timer-size-sm" size="sm" format="hh:mm" elapsed={15600} total={24000} />
    <.timer id="timer-size-md" size="md" format="hh:mm" elapsed={15600} total={24000} />
    <.timer id="timer-size-lg" size="lg" format="hh:mm" elapsed={15600} total={24000} />
  </div>
  <div class="flex flex-wrap items-center gap-2.5">
    <.timer id="timer-color-neutral" size="sm" color="neutral" format="hh:mm" elapsed={18000} total={45000} />
    <.timer id="timer-color-primary" size="sm" color="primary" format="hh:mm" elapsed={18000} total={37500} />
    <.timer id="timer-color-secondary" size="sm" color="secondary" format="hh:mm" elapsed={18000} total={32143} />
    <.timer id="timer-color-info" size="sm" color="info" format="hh:mm" elapsed={18000} total={28125} />
    <.timer id="timer-color-success" size="sm" color="success" format="hh:mm" elapsed={18000} total={25000} />
    <.timer id="timer-color-warning" size="sm" color="warning" format="hh:mm" elapsed={18000} total={22500} />
    <.timer id="timer-color-error" size="sm" color="error" format="hh:mm" elapsed={18000} total={20455} />
  </div>
</div>

variant mini · format

01:24:36 · hms 01:24 · hm 24:36 · auto
.heex
<%!-- the canvas draws the three formats as static samples ("value · format") --%>
<div class="flex flex-wrap items-center gap-2.5">
  <.timer id="timer-fmt-hms" variant="mini" running={false} elapsed={5076} format="hms"> · hms</.timer>
  <.timer id="timer-fmt-hm" variant="mini" running={false} elapsed={5076} format="hh:mm"> · hm</.timer>
  <.timer id="timer-fmt-auto" variant="mini" running={false} elapsed={1476} format="mm:ss"> · auto</.timer>
</div>

Usage

<.timer id="sessao" direction="down" seconds={600} variant="ring" />
<.timer id="t" direction="up" variant="mini" format="hms" />

Rules

  • Countdown: the ring empties; count-up: the ring fills.
  • mini fits in bars and table rows.

API reference

Todos os function components, atributos, valores e slots que este componente cobre.

A timer that ticks in the browser: a ring with the time in the middle (a shift, a countdown, any stretch of time) and a small pill of it for a top bar.

<.timer id="shift" elapsed={@shift_seconds} running={@running} kicker="Register open"
  kicker_paused="Paused" label="Register 01" on_toggle="shift_toggled">
  <:actions>
    <button phx-click={LedgerUI.Timer.toggle("shift")}>Pause</button>
    <button phx-click={LedgerUI.Timer.add("shift", 900)}>+15 min</button>
  </:actions>
</.timer>

<.timer id="break" direction="down" total={900} elapsed={0} color="warning" on_finish="break_over" />
<.timer id="mini" variant="mini" elapsed={@seconds} running={@running} label="Shift time" />

The server owns the time (elapsed, running, total, direction); the LedgerUI.Timer hook counts from there on a monotonic clock with no round trip, and a new value from the server replaces what the browser counted. format is hms (03:12:45), hm (3h12), hh:mm or mm:ss (192:45).

The timer is role="timer" named by label; the ticking text is not a live region. color is the ring while it runs (nothing is added by default); paused is always warning (the hook flips data-state between running and paused). Styled only with Tailwind utilities.

Events (on_toggle, on_tick, on_finish) take an event name or a %JS{} and go to target. Browser commands live in LedgerUI.Timer (pause/1, resume/1, toggle/1, add/2, and the socket versions to push them from the server).

<.timer>

Attr Type Default Values / notes
id (required) :string
elapsed :integer 0
total :integer 28800
seconds :integer nil The same as total (seconds={600} with direction="down" is a ten minute countdown).
running :boolean true
direction :string "up" up, down
variant :string "ring" ring, mini
size :string "md" sm, md, lg
color :string nil nil, neutral, primary, secondary, info, success, warning, error
format :string "auto" auto, hms, hm, hh:mm, mm:ss
kicker :string nil
kicker_paused :string nil
label :string nil
stop_at_total :boolean false
demo :boolean false The canvas CSS loop, no hook (a mini just stays still, with its dot): the ring fills (up) or empties (down) in 10s and the time counts 00:00..00:10 with a CSS counter (mo-tup/mo-tdown). For showcases.
on_toggle :any nil
on_tick :any nil
on_finish :any nil
target :any nil
class :any nil

Any other HTML/phx attribute goes to the root element.

Slots:

  • <:actions> - The controls under the ring (ring only).
  • <:caption> - Replaces the label line under the time (ring only).
  • <:inner_block> - mini: text after the time (a note on a static sample, · hms).