# Timer Ring

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

> Composed · Pro · Data Display — React Native, Expo Go compatible.

## Install

```bash
npx @lumioui/cli add pro/timer-ring
```

## Import

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

## Variants

- `focus` — Focus: `npx @lumioui/cli add pro/timer-ring-focus`
- `kitchen` — Kitchen: `npx @lumioui/cli add pro/timer-ring-kitchen`
- `rest` — Rest: `npx @lumioui/cli add pro/timer-ring-rest`
- `resume` — Resume: `npx @lumioui/cli add pro/timer-ring-resume`

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `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. |
| `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. |
| `strokeWidth?` | `number` | Ring stroke in pt. Default 10. |
| `extendBy?` | `number` | Seconds the extend chip adds. 0 hides it. Default 60. |
| `showEndTime?` | `boolean` | Show "Ends 3:42 PM" under the digits while running. Default true. |
| `showControls?` | `boolean` | Render the Cancel / Start-Pause row. Default true. |
| `startLabel?` | `string` | Label for the start button when idle. Default "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. |
| `className?` | `string` | — |

## Icons rendered

- `bell` — /icons.html?i=bell

Source: https://lumioui.com/components/timer-ring