https://github.com/umarsiddique010/use-timer-hooks
https://github.com/umarsiddique010/use-timer-hooks
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/umarsiddique010/use-timer-hooks
- Owner: umarSiddique010
- Created: 2025-06-19T15:47:47.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-19T15:48:09.000Z (about 1 year ago)
- Last Synced: 2025-06-19T16:26:55.873Z (about 1 year ago)
- Language: JavaScript
- Size: 0 Bytes
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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
```bash
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
```jsx
import { useTimeout } from "@mdus/use-timer-hooks";
function Message() {
const [show, setShow] = useState(true);
// Hide message after 3s
useTimeout(() => setShow(false), 3000);
return show ?
Hello! This disappears in 3 seconds.
: null;
}
```
### Countdown Using Interval
```jsx
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 (
Countdown: {seconds} {isIntervalActive ? "" : "(Done)"}
);
}
```
### Debounced Search Input
```jsx
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](https://github.com/umarSiddique010)
- LinkedIn: [md-umar-siddique](https://linkedin.com/in/md-umar-siddique)
- Twitter/X: [@umarSiddique010](https://twitter.com/umarSiddique010)
- Dev.to: [@umarSiddique010](https://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.