⏱️ ilias-use-debounce

A lightweight and type-safe React hook for debouncing function calls with built-in cancellation support and debouncing state tracking.

📦 Installation

npm install ilias-use-debounce
# or
yarn add ilias-use-debounce

🚀 Usage

Import and use the hook directly in your React components:

import { useDebounce } from "ilias-use-debounce";

function SearchComponent() {
  const [searchTerm, setSearchTerm] = useState("");

  const performSearch = (query: string) => {
    console.log("Searching for:", query);
    // Your search logic here
  };

  const [debouncedSearch, cancelSearch, isDebouncing] = useDebounce(
    performSearch,
    500,
  );

  return (
    <div>
      <input
        value={searchTerm}
        onChange={(e) => {
          setSearchTerm(e.target.value);
          debouncedSearch(e.target.value);
        }}
        placeholder="Search..."
      />
      <button onClick={cancelSearch}>Cancel</button>
      {isDebouncing && <span>Searching...</span>}
    </div>
  );
}

🧩 API Reference

useDebounce<T>(fn: T, delay: number): [(...args: Parameters<T>) => void, () => void, boolean]

Debounces a function call, delaying its execution until after the specified delay has elapsed since the last call.

Parameters

• fn: The function to debounce. Can be synchronous or asynchronous.
• delay: The delay in milliseconds. Negative values are treated as 0.

Returns

An array with three elements:

1. debounce (...args: Parameters<T>) => void - The debounced function to call.
2. cancel () => void - Function to cancel any pending debounced call.
3. debouncing boolean - State indicating if there's a pending debounced call.

💡 Use Cases

• Search inputs: Delay API calls until the user stops typing
• Form validation: Validate input after the user finishes editing
• Auto-save: Save data after the user stops making changes
• Window resize handlers: Limit expensive recalculations during resize
• Scroll events: Reduce the frequency of scroll event handlers

✨ Features

• ✅ TypeScript support - Full type safety with inferred parameter types
• ✅ Cancellation - Cancel pending debounced calls on demand
• ✅ State tracking - Know when a debounced call is pending
• ✅ Async support - Works with both sync and async functions
• ✅ Zero dependencies - Only requires React
• ✅ Small bundle size - Minimal footprint
• ✅ Well tested - Comprehensive test coverage with Vitest

🧪 Testing

This library uses Vitest for testing.

npm test

🤝 Contributing

We welcome contributions!

• See CONTRIBUTING.md for branch and commit conventions.
• See CODE_OF_CONDUCT.md to understand our community expectations.

🛡️ License

This project is licensed under the ISC License.

💡 How It Works

The useDebounce hook creates a debounced version of your function that:

1. Delays execution until delay milliseconds have passed since the last call
2. Cancels any previous pending execution when called again
3. Tracks the debouncing state so you can show loading indicators
4. Preserves the latest arguments passed to the function