useCountdown

v0.0.14testeddemo

Reactive countdown timer exposing the remaining seconds plus start/stop/pause/resume/reset controls and onTick/onComplete callbacks. Built on useIntervalFn, so it is SSR-safe and cleans up on scope dispose.

Source Tests

Examples

const { remaining, start, pause, resume, stop } = useCountdown(60);
start();

useCountdown(10, {
  immediate: true,
  onTick: (n) => console.log(n),
  onComplete: () => console.log('done'),
});

Demo

Loading demo…

Signature

export function useCountdown(
  initialCountdown: MaybeRefOrGetter<number>,
  options: UseCountdownOptions ={ ... }

Parameters

Parameter	Type	Default	Description
`initialCountdown`	`MaybeRefOrGetter<number>`	—	The starting value, in seconds (can be reactive)
`options`?	`UseCountdownOptions`	`{}`	Options

Returns

UseCountdownReturnThe reactive remaining value and countdown controls

Property	Type	Default	Description
`remaining`	`Readonly<ShallowRef<number>>`	—	The remaining seconds, read-only (use `reset`/`start` to change it)
`isActive`	`UseIntervalFnReturn['isActive']`	—	Whether the countdown is currently running
`reset`	`(countdown?: MaybeRefOrGetter<number>) => void`	—	Reset `remaining` (defaults to the initial value) without changing the running state
`stop`	`() => void`	—	Pause the countdown and reset `remaining` to the initial value
`start`	`(countdown?: MaybeRefOrGetter<number>) => void`	—	Reset `remaining` (defaults to the initial value) and start counting down