useCountdown

Reactive countdown timer with pause/resume/reset controls

A reactive countdown timer built on useIntervalFn. Decrements a counter by 1 on each tick, auto-pauses at 0, and provides full Pausable controls plus reset, stop, and start.

Demo

Countdown

Paused

60-second countdown with pause, resume, reset, stop, and start controls.

60

ResumeResetStopStart

Usage

Basic

Hook

import { useCountdown } from "@usels/web";

function Component() {
  const { remaining$ } = useCountdown(60);
  return <div>{remaining$.get()}</div>;
  // remaining$.get() → 60, 59, 58, ... 0
}

Scope

import { createCountdown } from "@usels/web";

function Component() {
  "use scope"
  const { remaining$ } = createCountdown(60);
  return <div>{remaining$.get()}</div>;
  // remaining$.get() → 60, 59, 58, ... 0
}

With callbacks

Hook

import { useCountdown } from "@usels/web";

function Component() {
  const { remaining$ } = useCountdown(10, {
    onTick: (remaining) => console.log(`${remaining}s left`),
    onComplete: () => console.log("Done!"),
  });
}

Scope

import { createCountdown } from "@usels/web";

function Component() {
  "use scope"
  const { remaining$ } = createCountdown(10, {
    onTick: (remaining) => console.log(`${remaining}s left`),
    onComplete: () => console.log("Done!"),
  });
}

Custom interval

Hook

import { useCountdown } from "@usels/web";

function Component() {
  // Tick every 500ms instead of the default 1000ms
  const { remaining$ } = useCountdown(30, { interval: 500 });
}

Scope

import { createCountdown } from "@usels/web";

function Component() {
  "use scope"
  // Tick every 500ms instead of the default 1000ms
  const { remaining$ } = createCountdown(30, { interval: 500 });
}

Manual start

Hook

import { useCountdown } from "@usels/web";

function Component() {
  const { remaining$, start } = useCountdown(10, { immediate: false });
  // remaining$.get() === 10 (not started)
  // start() to begin countdown
}

Scope

import { createCountdown } from "@usels/web";

function Component() {
  "use scope"
  const { remaining$, start } = createCountdown(10, { immediate: false });
  // remaining$.get() === 10 (not started)
  // start() to begin countdown
}

Reset / Stop / Start controls

Hook

import { useCountdown } from "@usels/web";

function Component() {
  const { remaining$, reset, stop, start, pause, resume } = useCountdown(60);

  // reset()       → remaining$ back to 60 (timer keeps running)
  // reset(30)     → remaining$ set to 30
  // stop()        → pause + reset (fully stop)
  // start()       → reset + resume (restart)
  // start(30)     → reset to 30 + resume
  // pause()       → freeze countdown
  // resume()      → continue from current remaining$
}

Scope

import { createCountdown } from "@usels/web";

function Component() {
  "use scope"
  const { remaining$, reset, stop, start, pause, resume } = createCountdown(60);

  // reset()       → remaining$ back to 60 (timer keeps running)
  // reset(30)     → remaining$ set to 30
  // stop()        → pause + reset (fully stop)
  // start()       → reset + resume (restart)
  // start(30)     → reset to 30 + resume
  // pause()       → freeze countdown
  // resume()      → continue from current remaining$
}

Type

Parameters

Parameter	Type	Description
initialCount	MaybeObservable<number>	-
options	CountdownOptions (optional)	-

CountdownOptions

Option	Type	Default	Description
interval	number	1000	Interval between ticks in ms
immediate	boolean	true	Auto-start on creation
onTick	((remaining: number) => void)	-	Callback on each tick
onComplete	(() => void)	-	Callback when countdown reaches 0

Returns

CountdownReturn

Name	Type	Description
remaining$	ObservablePrimitive<number>	Current remaining count
reset	(count?: number | undefined) => void	Reset to initial count or custom value
stop	Fn	Pause + reset (stop the countdown entirely)
start	(count?: number | undefined) => void	Reset to initial/custom count + resume (restart)
isActive$	ReadonlyObservable<boolean>	-
pause	Fn	-
resume	Fn	-

Source

View on GitHub