npm package: @naba-zehra/react-debounce-hook
Description: A tiny React hook to debounce values
Latest version: 1.2.0

# @naba-zehra/react-debounce-hook

A tiny and simple React hook to debounce values. Perfect for search inputs, filters, and expensive operations.

## ✨ Features

* ⚡ Minimal and lightweight (~0.3 kB gzipped)
* 🎯 Easy to use with any value type
* 🚀 Zero dependencies
* 📱 Works with React 17+
* ✅ TypeScript support

---

## 📦 Installation

```bash
npm install @naba-zehra/react-debounce-hook
```

or with yarn:

```bash
yarn add @naba-zehra/react-debounce-hook
```

---

## 🚀 Quick Start

```jsx
import { useState, useEffect } from "react";
import { useDebounce } from "@naba-zehra/react-debounce-hook";

export function SearchComponent() {
  const [searchTerm, setSearchTerm] = useState("");
  const debouncedSearchTerm = useDebounce(searchTerm, 500);

  useEffect(() => {
    if (!debouncedSearchTerm) return;
    
    // Perform API call or expensive operation here
    console.log("Searching for:", debouncedSearchTerm);
    // fetchResults(debouncedSearchTerm);
  }, [debouncedSearchTerm]);

  return (
    <input
      type="text"
      value={searchTerm}
      onChange={(e) => setSearchTerm(e.target.value)}
      placeholder="Search products..."
    />
  );
}
```

---

## 📖 API Reference

### `useDebounce(value, delay?)`

A hook that debounces any value with optional delay.

**Parameters:**

| Parameter | Type     | Default | Description              |
| --------- | -------- | ------- | ------------------------ |
| `value`   | any      | -       | The value to debounce    |
| `delay`   | number   | 300     | Delay in milliseconds    |

**Returns:** The debounced value

**Example:**

```js
const debouncedValue = useDebounce(value, 500);
```

---

## 💡 Common Use Cases

### 1. Search Input
```jsx
const [query, setQuery] = useState("");
const debouncedQuery = useDebounce(query, 500);

useEffect(() => {
  if (debouncedQuery) {
    searchAPI(debouncedQuery);
  }
}, [debouncedQuery]);
```

### 2. Live Filtering
```jsx
const [filter, setFilter] = useState("");
const debouncedFilter = useDebounce(filter, 300);

const filtered = items.filter(item => 
  item.name.includes(debouncedFilter)
);
```

### 3. Auto-save Form
```jsx
const [formData, setFormData] = useState({});
const debouncedData = useDebounce(formData, 1000);

useEffect(() => {
  if (Object.keys(debouncedData).length > 0) {
    saveToDatabase(debouncedData);
  }
}, [debouncedData]);
```

---

## ⚙️ How It Works

The hook delays updating the returned value until the input stops changing for the specified delay.

**Example Timeline:**

**Without debounce - User types "hello":**
```
User types:  h  e  l  l  o
API calls:   1  2  3  4  5   (5 calls ❌)
```

**With debounce (500ms delay):**
```
User types:  h--e--l--l--o
API calls:   1 (after 500ms)  (1 call ✅)
```

---

## 📌 Best Practices

✅ **DO:**
- Use for expensive operations (API calls, complex filtering)
- Use with `useEffect` for side effects
- Combine with loading states for better UX

❌ **DON'T:**
- Use the debounced value as form input value (use the original state)
- Forget to add debounced value to dependency arrays
- Use very small delays (< 100ms) as it defeats the purpose

---

## 🤝 Contributing

Found a bug or want to suggest a feature? [Open an issue](https://github.com/Naba-cloud/react-debounce-input/issues)

---

## 📄 License

MIT