Timer / Countdown

Countdown (`duration` ms) or stopwatch. Start/pause/reset; announces completion once (visual digits are hidden from AT while running).

Import

import { Timer } from '@marbleui/ui'

Props

<Timer>

Prop	Type	Default
className	`string`	`—`
duration	`number`	`5 * 60_000`
mode	`'countdown' \| 'stopwatch'`	`'countdown'`
onComplete	`() => void`	`—`

Usage notes

Timer is a countdown with a progress ring, or a stopwatch with hundredths of a second, with its own Start/Pause/Resume and Reset buttons. To show progress of a task rather than time, use ProgressCircle.

<Timer duration={25 * 60_000} onComplete={() => toast({ title: 'Focus session finished' })} />
<Timer mode="stopwatch" />

duration is in milliseconds (default 5 minutes). There are no props to start, pause or reset it from outside, or to read the elapsed time; only its buttons drive it.
While it runs, the digits are hidden from screen readers so they aren’t read out on every tick; they are readable when paused. When a countdown ends, “Time is up” is announced once. The stopwatch announces nothing.
The countdown rounds up, so a 10-second timer shows 0:10 at the start and 0:00 only when it ends. Changing duration, mode or onComplete while it runs takes effect immediately.
It ticks on requestAnimationFrame. In a background tab it keeps time, but onComplete and the announcement wait until the tab is visible again.

Example source · show

import { Timer } from './timer'

export const styles = { Countdown: () => <Timer duration={10_000} />, Stopwatch: () => <Timer mode="stopwatch" /> }

Source: packages/ui/src/timer/timer.tsx

Catalog