Timer Ring

Pro

Countdown shown as a ring that drains as time passes, with pause, resume and a one-minute extend. The last ten seconds count down digit by digit and it finishes on “Done”.

Preview

Installation

npx @lumioui/cli add pro/timer-ring

Usage

import { formatCountdown, TimerRing } from "@/components/ui/timer-ring/timer-ring";
<TimerRing />

Also exported: formatCountdown.

Examples

Focus

A pomodoro session in a task app.

Kitchen

A recipe step timer for soft-boiled eggs.

Rest

The rest timer between sets in a lifting log.

Resume

A study app reopened mid-session.

API reference

Prop Type Default
duration* number

Countdown length in seconds — the full block the ring represents. Changing it resets the timer.

 —
remaining number

Controlled time left, in seconds — the parent owns it (e.g. a session restored from storage or synced from a server). The ring re-anchors when this differs from its own clock by more than a second, so feeding onRemainingChange straight back in never stalls the countdown.

 —
defaultRemaining number

Uncontrolled starting time left, in seconds — resume at 18:40 of 25:00. Default duration.

 —
onRemainingChange (seconds: number) => void

Fires with the whole seconds left on each second while running, and on pause / extend / cancel / complete.

 —
running boolean

Controlled running state.

 —
defaultRunning boolean

Uncontrolled initial running state. Default false.

 false
onRunningChange (running: boolean) => void

Fires when start / pause / resume / cancel change the running state.

 —
onComplete () => void

Fires once when the countdown reaches zero.

 —
onCancel () => void

Fires when Cancel resets the timer.

 —
label string

Line above the digits — "Focus", "Rest".

 —
size number

Ring diameter in pt. Default 260.

 260
strokeWidth number

Ring stroke in pt. Default 10.

 10
extendBy number

Seconds the extend chip adds. 0 hides it. Default 60.

 60
showEndTime boolean

Show "Ends 3:42 PM" under the digits while running. Default true.

 true
showControls boolean

Render the Cancel / Start-Pause row. Default true.

 true
startLabel string

Label for the start button when idle. Default "Start".

 "Start"
completeHold number

Hold the lit "Done" ring this long (ms) before onComplete fires, so the moment lands before a parent moves on (e.g. 700 for a rest timer that advances sets). Default 0 — onComplete fires at zero.

 0
className string —