useTimer

A lightweight, reusable React hook package that provides two battle-tested utilities: useTimeout and useInterval. These help you manage time-based side effects in React apps — cleanly and safely.

Fully React-idiomatic · Auto Cleanup · Functional-safe · Zero Dependencies

Features

• Delay Execution (Timeout) — run code after a specified delay
• Repeat Execution (Interval) — run code at a set frequency
• No Memory Leaks — auto-clears timers on unmount
• Safe Callback Handling — avoids stale closures
• Manual Control — start, stop, reset methods
• Tiny and Efficient — no dependencies except React

Installation

npm install @mdus/use-timer-hooks
# or
yarn add @mdus/use-timer-hooks

API Overview

useTimeout(callback, delay)

Runs a function once after the given delay (in milliseconds).

Parameter	Type	Required	Description
callback	() => void	✅	Function to run once after delay
delay	number	✅	Time in ms to wait before firing

Returns

Key	Type	Description
startTimeout()	function	Start (or restart) the timeout
stopTimeout()	function	Cancel the timeout
resetTimeout()	function	Reset the timeout (stop + start)
isTimeoutActive	boolean	True while the timeout is counting down

Behavior

• If delay is invalid (null, false, etc), nothing runs
• Automatically stops on component unmount
• Callback is kept in sync (doesn't go stale)

useInterval(callback, delay)

Runs a function repeatedly at the given interval (in milliseconds).

Parameter	Type	Required	Description
callback	() => void	✅	Function to run on each interval
delay	number	✅	Time between runs (in milliseconds)

Returns

Key	Type	Description
startInterval()	function	Starts the interval
stopInterval()	function	Stops the interval
resetInterval()	function	Stops and restarts the interval
isIntervalActive	boolean	True while the interval is running

Examples

Basic Timeout

import { useTimeout } from "@mdus/use-timer-hooks";

function Message() {
  const [show, setShow] = useState(true);

  // Hide message after 3s
  useTimeout(() => setShow(false), 3000);

  return show ? <p>Hello! This disappears in 3 seconds.</p> : null;
}

Countdown Using Interval

import { useInterval } from "@mdus/use-timer-hooks";

function Countdown() {
  const [seconds, setSeconds] = useState(10);

  const { stopInterval, isIntervalActive } = useInterval(() => {
    setSeconds((prev) => {
      if (prev <= 1) {
        stopInterval(); // Stop when we hit 0
        return 0;
      }
      return prev - 1;
    });
  }, 1000);

  return (
    <p>
      Countdown: {seconds} {isIntervalActive ? "" : "(Done)"}
    </p>
  );
}

Debounced Search Input

import { useTimeout } from "@mdus/use-timer-hooks";

function DebouncedSearch({ value, onSearch }) {
  const { resetTimeout } = useTimeout(() => {
    onSearch(value);
  }, 500); // debounce 500ms

  useEffect(() => {
    resetTimeout(); // re-trigger on value change
  }, [value]);

  return null;
}

Internal Notes

• We use useRef to store the latest version of your callback to prevent stale closure issues.
• Both hooks automatically clear timers when the component unmounts — you don't need to worry about leaks or race conditions.
• Manual startX(), stopX(), and resetX() functions give you full control.

Folder Structure

use-timer-hooks/
├── src/
│   └── useTimer.js
├── dist/
│   └── index.js
├── package.json
├── README.md
└── LICENSE

Author

Md Umar Siddique
Frontend-first engineer building real-world tools with long-term value.

• GitHub: @umarSiddique010

• LinkedIn: md-umar-siddique

• Twitter/X: @umarSiddique010

• Dev.to: @umarSiddique010

Contributing

Pull requests are welcome! If you'd like to improve anything or need another timing hook, open an issue or PR.

License

MIT License — use freely, credit appreciated.