@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

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

or with yarn:

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

🚀 Quick Start

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:

const debouncedValue = useDebounce(value, 500);

💡 Common Use Cases

1. Search Input

const [query, setQuery] = useState("");
const debouncedQuery = useDebounce(query, 500);

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

2. Live Filtering

const [filter, setFilter] = useState("");
const debouncedFilter = useDebounce(filter, 300);

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

3. Auto-save Form

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

📄 License

MIT