useCountdown

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

60

paused

ResumeResetStopStart

Usage

Basic

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

const { remaining$ } = useCountdown(60);
// remaining$.get() → 60, 59, 58, ... 0

With callbacks

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

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

Custom interval

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

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

Manual start

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

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

Reset / Stop / Start controls

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

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$

Type Declarations

export interface UseCountdownOptions {
    interval?: number;
    immediate?: boolean;
    onTick?: (remaining: number) => void;
    onComplete?: () => void;
}
export interface UseCountdownReturn extends Pausable {
    remaining$: ReadonlyObservable<number>;
    reset: (count?: number) => void;
    stop: Fn;
    start: (count?: number) => void;
}
export declare function useCountdown(initialCount: MaybeObservable<number>, options?: DeepMaybeObservable<UseCountdownOptions>): UseCountdownReturn;

Source

View on GitHub

Contributors

• tigerwest

Changelog

• a7392ab 2026-03-06 - feat(core,browser): add sync strategy hooks (tigerwest)