# `LedgerUI.Components.Timer`
[🔗](https://github.com/devaction-labs/ledger_ui/blob/v0.2.0/lib/ledger_ui/components/timer.ex#L1)

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`) or `hh:mm`.

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.

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`

## Attributes

* `id` (`:string`) (required)
* `elapsed` (`:integer`) - Defaults to `0`.
* `total` (`:integer`) - Defaults to `28800`.
* `seconds` (`:integer`) - The same as `total` (`seconds={600}` with `direction="down"` is a ten minute countdown). Defaults to `nil`.
* `running` (`:boolean`) - Defaults to `true`.
* `direction` (`:string`) - Defaults to `"up"`. Must be one of `"up"`, or `"down"`.
* `variant` (`:string`) - Defaults to `"ring"`. Must be one of `"ring"`, or `"mini"`.
* `size` (`:string`) - Defaults to `"md"`. Must be one of `"sm"`, `"md"`, or `"lg"`.
* `color` (`:string`) - Defaults to `nil`.Must be one of `nil`, `"neutral"`, `"primary"`, `"secondary"`, `"info"`, `"success"`, `"warning"`, or `"error"`.
* `format` (`:string`) - Defaults to `"auto"`. Must be one of `"auto"`, `"hms"`, `"hm"`, or `"hh:mm"`.
* `kicker` (`:string`) - Defaults to `nil`.
* `kicker_paused` (`:string`) - Defaults to `nil`.
* `label` (`:string`) - Defaults to `nil`.
* `stop_at_total` (`:boolean`) - Defaults to `false`.
* `on_toggle` (`:any`) - Defaults to `nil`.
* `on_tick` (`:any`) - Defaults to `nil`.
* `on_finish` (`:any`) - Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `actions` - The controls under the ring (`ring` only).
* `caption` - Replaces the `label` line under the time (`ring` only).

---

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