Timer
A React component in Beamline's Feedback category.
A duration that counts down (or up) from your clock: Start, Pause, Resume, Reset and the finish reported once; the time left drawn as a bar you drag (or step with ←/→) to give more or less time; a compact inline button for a timed round beside its value; resumes right after the page was away.
Use it for
- A rest between rounds, a timed set or drill, a cooking step, a focus block: any short duration a person starts, pauses and adjusts by feel.
- Counting time up since a start (a session, a call) with Pause and Reset.
Not for
- A deadline at a date and time (a date with relative words, or funding-countdown for a market's next funding).
- Time spent while saving or loading (useElapsed and the part's own busy state).
- Picking a time of day (time-picker).
Anatomy
- large: what it times, the time in large tabular digits with its word (left, paused, elapsed, done), the time left as a bar (the whole duration faint behind it), Start/Pause/Resume and Reset
- inline: one button with Play, Pause or a check and the time
- a polite status line that says the finish once
States
- idle
- running
- paused (digits dimmed, said)
- done (success tone with the word, Start again)
- counting up (no bar)
- resumed after the page was away
- finished while away (done on return, reported once)
- bar held (the value beside the hand)
- inline: idle, running, paused, done
Keyboard
- Start/Pause and Reset are buttons
- the bar (a slider, when the duration can change): → / ← five seconds (Shift: thirty), mirrored right to left
- inline: Enter or Space starts and pauses
Motion
The digits change once a second while running and never animate; the bar steps with them. Nothing renders or runs while idle, paused or done. Reduced motion changes nothing (nothing glides).
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label (required) | string | — | What it times, said with every value: "Rest", "Plank, set 2". |
duration / onDurationChange (required) | number | null / (seconds) => void | — | duration: Seconds to count down; null counts up (time since start) with no end. onDurationChange: Or change the duration (the bar, its keys). Without it the duration is fixed. |
state / defaultState / onStateChange | TimerState | — | { status, elapsedMs, runningSince }: store it and the timer resumes right after a reload. |
onComplete | () => void | — | The countdown reached zero: called once per run (also when it finished while the page was away). |
form | "large" | "inline" | — | large: digits, a bar you can drag, Start/Pause and Reset. inline: one compact button beside a value. |
step / max | number | — | step: Seconds the bar and its keys step by. Default 5. max: The longest duration the bar reaches, in seconds. Default twice the duration (at least a minute, in 30 s), so a rest has room to grow; it changes only after a release, never under the hand. |
clock | () => number | — | Your clock (ms since the epoch). Default Date.now. |
labels | MessageLabels | — | Your words for the built-in ones. |
duration (required) | number | null | — | Seconds to count down; null counts up (time since start) with no end. |
onDurationChange | ((seconds: number) => void) | — | Or change the duration (the bar, its keys). Without it the duration is fixed. |
state | TimerState | — | |
defaultState | TimerState | — | |
onStateChange | ((state: TimerState) => void) | — | Every start, pause, resume, reset and the finish, as the whole new state. Store it to survive a reload. |
step | number | — | Seconds the bar and its keys step by. Default 5. |
max | number | — | The longest duration the bar reaches, in seconds. Default twice the duration (at least a minute, in 30 s), so a rest has room to grow; it changes only after a release, never under the hand. |
className | string | — | Classes on the documented visual root; no override by default. |
style | CSSProperties | — | Inline styles on the documented visual root; no overrides by default. |
ref | Ref<HTMLDivElement> | — | Receives the documented native target or imperative handle; omitted by default. |
Built from
Used in
Dependencies
lucide-react
Import
import { Timer, TIMER_IDLE } from "@beamline/timer";Get it
Timer is part of Beamline UI. Install the parts you need in your React app as compiled packages or editable source. Get Beamline · Connect your agent
More in Feedback
- Notification centre: Updates that wait to be read: a bell with the unread count opens All / Unread, new and earlier groups, and per item mark read or dismiss.
- Usage meter: An allowance and what fills it: one bar split by source, the room left, a warning near the limit and the overflow in its own red well past a notch at the…
- Alert: A message that stays until it is dealt with: what happened, what to do, an action; danger and warning are announced; dismissing folds its height away.
- Cookie consent: Asks once which cookies a visitor allows, with Reject all and Accept all given equal weight; Customise grows the notice in place into each category with…
- Empty state: What a place will hold and the first step to fill it, instead of a blank; a compact size for panels and filtered tables.
- Spinner: A ring that spins while work runs and closes into a drawn check or cross when it ends.
- Announcement bar: A banner across the top for news and offers: messages take turns, a countdown ticks, and dismissing folds it away and can remember it.
- Progress: How much of a known task is done, or a moving bar when the length is unknown, with an optional label and value.
- Skeleton: Holds the shape of content while it loads, then crossfades into it, so nothing jumps.