Multi-Debounce
Smart debouncing utility that allows immediate execution on certain triggers (like Enter key or paste) while maintaining standard debouncing for regular input changes.
Why Multi-Debounce?
When building search inputs, you typically want to:
- Debounce regular typing to avoid excessive API calls
- Execute immediately when user presses Enter or pastes text
- Avoid complex state management that comes with controlling this behavior in React
With standard useDebounce
, you'd need additional state to handle immediate execution scenarios. Multi-Debounce solves this by providing multiple debounced functions with different delays that automatically cancel each other.
Installation
npm install multi-debounce
Usage
React Hook
import { useMultiDebounce } from "multi-debounce/useMultiDebounce";
function SearchInput() {
const search = useMultiDebounce((query: string) => {
console.log("Searching for:", query);
});
const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
search.m(e.target.value);
};
const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
if (e.key === "Enter") {
search.none((e.target as HTMLInputElement).value);
}
};
const handlePaste = (e: React.ClipboardEvent<HTMLInputElement>) => {
search.none(e.clipboardData.getData("text"));
};
return (
<input
type="text"
onChange={handleInputChange}
onKeyDown={handleKeyDown}
onPaste={handlePaste}
placeholder="Search..."
/>
);
}
Vanilla JavaScript
import { multiDebounce } from "multi-debounce/mutliDebounce";
const search = multiDebounce((query) => {
console.log("Searching for:", query);
});
input.addEventListener("input", (e) => {
search.m(e.target.value);
});
input.addEventListener("keydown", (e) => {
if (e.key === "Enter") {
search.none(e.target.value);
}
});
input.addEventListener("paste", (e) => {
search.none(e.clipboardData.getData("text"));
});
Available Delays
The library provides pre-configured delays:
{
none: 0,
xs: 10,
s: 50,
m: 200,
l: 1000,
xl: 3000,
0: 0,
50: 50,
100: 100,
200: 200,
500: 500,
1000: 1000,
2000: 2000,
3000: 3000
}
Custom Delays
You can provide custom delay configurations:
const customDelays = {
immediate: 0,
fast: 100,
slow: 800,
};
const debouncedFn = useMultiDebounce(myFunction, customDelays);
const debouncedFn = multiDebounce(myFunction, customDelays);
debouncedFn.immediate(data);
debouncedFn.fast(data);
debouncedFn.slow(data);
Advanced Usage
Manual Control
const search = multiDebounce(searchFunction);
search.cancelAll();
search.flushAll();
search.m.cancel();
search.m.flush();
Form Validation Example
function EmailInput() {
const validateEmail = useMultiDebounce((email: string) => {
if (isValidEmail(email)) {
checkEmailAvailability(email);
}
});
return (
<input
type="email"
onChange={(e) => validateEmail.m(e.target.value)} // 200ms delay
onBlur={(e) => validateEmail.s(e.target.value)} // 50ms delay on blur
/>
);
}
TypeScript Support
Fully typed with TypeScript. Generic types preserve function signatures:
const typedDebounce = useMultiDebounce(
(id: number, name: string) => Promise<User>,
{ quick: 100, normal: 300 },
);
typedDebounce.quick(1, "John");
typedDebounce.normal(2, "Jane");
License
MIT