Countdown

Feedback

A ticking timer with clock and circular variants.

The Countdown counts down from a given number of seconds. Control it with running and onRunningChange, or imperatively through the CountdownHandle exposed via ref.

npx shadcn@latest add countdown

Interactive

Start, pause, and reset the timer with the controls below.

Preview

Live

01:30

tsx

1const [running, setRunning] = useState(false)
2
3<Countdown
4  seconds={90}
5  running={running}
6  onRunningChange={setRunning}
7  onComplete={reset}
8/>

Variants

Switch between the clock and circular displays.

Preview

Live

01:30

tsx

1<Countdown seconds={300} variant="clock" autoStart />
2<Countdown seconds={60} variant="circular" />

API reference

All props of the underlying Base UI primitive are forwarded. The table below documents the Shelf-specific props.

Prop	Type	Description
seconds	number	Total duration to count down from.
variant	"clock" \| "circular"= "clock"	Visual display of the timer.
autoStart	boolean= false	Start counting on mount.
onComplete	() => void	Called once the countdown reaches zero.
running	boolean	Controlled running state.
onRunningChange	(running) => void	Called when the timer starts or stops.
ref	CountdownHandle	Imperative handle with start, pause, and reset.