React useCountdown Hook

Ever built a countdown timer and realized you're juggling setInterval, clearInterval, state management, boundary checks, and cleanup logic? You know the drill—track the interval ID, handle component unmounts, deal with stale closures. This free open source React useCountdown custom hook handles all that timer complexity so you can focus on your UI instead of fighting with JavaScript timing quirks in your React applications.

useCountdown showcase

Flexible countdown timer with full control:

"use client";import { useState, useEffect } from "react";import { toast } from "sonner";import { Button } from "@/components/ui/button";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { Slider } from "@/components/ui/slider";import { useCountdown } from "@/components/ui/shadcn-io/use-countdown";export default function UseCountdownDemo() {  const [intervalValue, setIntervalValue] = useState<number>(1000);  const [count, { startCountdown, stopCountdown, resetCountdown }] =    useCountdown({      countStart: 30,      intervalMs: intervalValue,    });  const handleStart = () => {    startCountdown();    toast.success("Timer started!", {      description: `Countdown running for ${count} seconds`,    });  };  const handleStop = () => {    stopCountdown();    toast.info("Timer paused", {      description: "Click start to resume",    });  };  const handleReset = () => {    resetCountdown();    toast("Timer reset", {      description: "Ready to start a new countdown",    });  };  // Show completion toast when timer reaches 0  useEffect(() => {    if (count === 0) {      toast.success("Time's up! 🎉", {        description: "Your countdown has finished",      });    }  }, [count]);  return (    <div className="p-6 max-w-sm mx-auto space-y-6">      {/* Header */}      <div className="text-center space-y-2">        <h3 className="text-lg font-semibold">Countdown Timer Demo</h3>        <p className="text-sm text-muted-foreground">Basic useCountdown hook functionality</p>      </div>            {/* Timer Display */}      <div className="text-center space-y-3">        <Label className="text-sm font-medium">Current Time</Label>        <div className="min-h-[60px] flex items-center justify-center">          <Badge             variant={count === 0 ? "destructive" : count <= 5 ? "secondary" : "default"}             className="text-3xl px-6 py-3 font-mono font-bold"          >            {count}s          </Badge>        </div>      </div>      {/* Control Buttons - Fixed height container to prevent layout shift */}      <div className="space-y-2">        <div className="flex gap-2 min-h-[36px]">          <Button            onClick={handleStart}            disabled={count === 0}            variant="default"            size="sm"            className="flex-1 text-sm h-9"          >            Start          </Button>          <Button            onClick={handleStop}            variant="outline"            size="sm"            className="flex-1 text-sm h-9"          >            Stop          </Button>          <Button            onClick={handleReset}            variant="outline"            size="sm"            className="flex-1 text-sm h-9"          >            Reset          </Button>        </div>      </div>      {/* Speed Control */}      <div className="space-y-2">        <div className="flex items-center justify-between min-h-[20px]">          <Label className="text-sm font-medium">Speed</Label>          <Badge variant="secondary" className="text-xs px-2 py-0.5">            {intervalValue}ms          </Badge>        </div>        <div className="min-h-[20px] flex items-center">          <Slider            value={[intervalValue]}            onValueChange={(value) => setIntervalValue(value[0])}            min={200}            max={2000}            step={200}            className="w-full"          />        </div>      </div>      {/* Status Display - Fixed height to prevent shift */}      <div className="text-center min-h-[20px] flex items-center justify-center">        <div className="text-xs text-muted-foreground">          Timer updates every <code className="bg-muted px-1 py-0.5 rounded text-xs">{intervalValue}ms</code>        </div>      </div>    </div>  );}

"use client"import { useCallback } from "react"import { useBoolean } from "@/components/ui/kibo-ui/use-boolean"import { useCounter } from "@/components/ui/kibo-ui/use-counter"import { useInterval } from "@/components/ui/kibo-ui/use-interval"type CountdownOptions = {  countStart: number  intervalMs?: number  isIncrement?: boolean  countStop?: number}type CountdownControllers = {  startCountdown: () => void  stopCountdown: () => void  resetCountdown: () => void}export function useCountdown({  countStart,  countStop = 0,  intervalMs = 1000,  isIncrement = false,}: CountdownOptions): [number, CountdownControllers] {  const {    count,    increment,    decrement,    reset: resetCounter,  } = useCounter(countStart)  /*   * Note: used to control the useInterval   * running: If true, the interval is running   * start: Should set running true to trigger interval   * stop: Should set running false to remove interval.   */  const {    value: isCountdownRunning,    setTrue: startCountdown,    setFalse: stopCountdown,  } = useBoolean(false)  // Will set running false and reset the seconds to initial value.  const resetCountdown = useCallback(() => {    stopCountdown()    resetCounter()  }, [stopCountdown, resetCounter])  const countdownCallback = useCallback(() => {    if (count === countStop) {      stopCountdown()      return    }    if (isIncrement) {      increment()    } else {      decrement()    }  }, [count, countStop, decrement, increment, isIncrement, stopCountdown])  useInterval(countdownCallback, isCountdownRunning ? intervalMs : null)  return [count, { startCountdown, stopCountdown, resetCountdown }]}export type { CountdownOptions, CountdownControllers }

This free open source React hook simplifies timer management with TypeScript support for modern JavaScript applications. Whether you're building pomodoro timers, game countdowns, or session timeouts in your Next.js projects, this React hook keeps your timing logic clean and reliable.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-countdown.json

npx shadcn@latest add https://www.shadcn.io/registry/use-countdown.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-countdown.json

bunx shadcn@latest add https://www.shadcn.io/registry/use-countdown.json

Why most countdown implementations suck

Look, you could manually manage setInterval, track the interval ID, handle cleanup on unmount, and deal with React's closure issues. But after debugging the third "why is my timer jumping" bug, you'll appreciate having this handled properly.

Most developers forget to clear intervals when components unmount, causing memory leaks in React applications. Or they use inline functions that re-register timers on every render, creating performance issues. Some skip proper closure handling and wonder why their timer callbacks have stale values in TypeScript components.

The React hook automatically manages the entire timer lifecycle—proper cleanup, pause/resume functionality, and boundary checking. No more forgotten clearInterval calls or stale closure bugs in Next.js projects.

Plus it handles both countdown and count-up modes, custom intervals, and auto-stop conditions—all the stuff you'd eventually need to add anyway in JavaScript applications.

This free open source React hook handles the timer boilerplate while you focus on building features. Whether you're creating React applications, Next.js projects, or TypeScript codebases, this custom hook keeps your countdown logic bulletproof.

Features

• Flexible direction - Count down or count up with isIncrement option in React applications
• Configurable interval - Set custom intervals in milliseconds for TypeScript components
• Auto-stop - Automatically stops when reaching the target value in Next.js projects
• Full control - Start, stop, and reset functionality for JavaScript development
• Custom boundaries - Set custom start and stop values with proper validation
• Performance optimized - Uses efficient interval management to prevent memory leaks
• TypeScript support - Complete type definitions for all options and return values
• Free open source - Designed for modern React development workflows

Usage

import { useCountdown } from "@/hooks/use-countdown";

function Timer() {
  const [count, { startCountdown, stopCountdown, resetCountdown }] =
    useCountdown({
      countStart: 60,
      intervalMs: 1000,
    });

  return (
    <div>
      <div>Time: {count}</div>
      <button onClick={startCountdown}>Start</button>
      <button onClick={stopCountdown}>Stop</button>
      <button onClick={resetCountdown}>Reset</button>
    </div>
  );
}

API Reference

useCountdown

useCountdown(options: CountdownOptions): [number, CountdownControllers]

CountdownOptions

CountdownControllers

Return Value

Returns a tuple with:

• count: Current countdown value
• controllers: Object with control functions

When you'll actually use this

Real talk—this isn't for displaying the current time or simple delays in React applications. For those, use Date objects or setTimeout. But when you need interactive timers with pause/resume, this React hook shines in Next.js projects.

Perfect for:

• Countdown timers - Games, quizzes, or time-limited activities built with TypeScript
• Pomodoro technique - Work/break interval timers in productivity apps using React patterns
• Loading states - Timeout countdowns with visual progress indicators in JavaScript applications
• Game mechanics - Cooldowns, respawn timers, round timers for React gaming interfaces
• Session timeouts - User session expiration warnings in Next.js applications
• Exercise timers - Workout intervals and rest periods with TypeScript validation
• Auction timers - Bidding countdown displays with real-time updates in React components
• Event countdowns - Time until launches or deadlines using JavaScript timing

Common gotchas

JavaScript timers aren't perfectly accurate: setInterval can drift, especially with background tabs in React applications. For mission-critical timing, you'd need to track actual elapsed time with Date.now() in TypeScript components.

React 18 batches state updates: Rapid interval changes might not render every single value in Next.js projects. This is usually fine for UI timers but worth knowing for debugging.

Background tab throttling: Browsers throttle intervals in background tabs to save resources in JavaScript applications. Your timer might slow down when users switch tabs—a browser feature, not a bug.

Automatic boundary stopping: When it reaches countStop, the timer stops in React components. If you need it to continue or loop, you'll need to handle that in your component with useEffect.

Memory leaks from improper cleanup: The most common mistake is forgetting interval cleanup when components unmount in TypeScript projects. This React hook handles the lifecycle automatically.

Related hooks you will also like

Questions you might have