@usefy/use-debounce

A feature-rich React hook for debouncing values with leading/trailing edge and maxWait support

Installation •
Quick Start •
API Reference •
Examples •
License

📚 View Storybook Demo

---

Overview

@usefy/use-debounce is a powerful React hook for debouncing values with advanced options like leading edge, trailing edge, and maximum wait time. Perfect for search inputs, form validation, API calls, and any scenario where you need to limit the rate of value updates.

Part of the @usefy ecosystem — a collection of production-ready React hooks designed for modern applications.

$3

- Zero Dependencies — Pure React implementation with no external dependencies
- TypeScript First — Full type safety with generics and exported interfaces
- Flexible Options — Leading edge, trailing edge, and maxWait support
- SSR Compatible — Works seamlessly with Next.js, Remix, and other SSR frameworks
- Lightweight — Minimal bundle footprint (~400B minified + gzipped)
- Well Tested — Comprehensive test coverage with Vitest

---

Installation

``bash


npm

npm install @usefy/use-debounce

yarn

yarn add @usefy/use-debounce

pnpm

pnpm add @usefy/use-debounce
`

$3

This package requires React 18 or 19:

`json
{
"peerDependencies": {
"react": "^18.0.0 || ^19.0.0"
}
}
`

---

Quick Start

`tsx
import { useDebounce } from "@usefy/use-debounce";

function SearchInput() {
const [query, setQuery] = useState("");
const debouncedQuery = useDebounce(query, 300);

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

return (
type="text"
value={query}
onChange={(e) => setQuery(e.target.value)}
placeholder="Search..."
/>
);
}
`

---

API Reference

$3

A hook that returns a debounced version of the provided value.

#### Parameters

| Parameter | Type | Default | Description |
| --------- | -------------------- | ------- | ---------------------------------- |
| value | T | — | The value to debounce |
| delay | number | 500 | The debounce delay in milliseconds |
| options | UseDebounceOptions | {} | Additional configuration options |

#### Options

| Option | Type | Default | Description |
| ---------- | --------- | ------- | --------------------------------------------- |
| leading | boolean | false | Update on the leading edge (first call) |
| trailing | boolean | true | Update on the trailing edge (after delay) |
| maxWait | number | — | Maximum time to wait before forcing an update |

#### Returns

| Type | Description |
| ---- | ------------------- |
| T | The debounced value |

---

Examples

$3

`tsx
import { useDebounce } from "@usefy/use-debounce";

function SearchInput() {
const [query, setQuery] = useState("");
const debouncedQuery = useDebounce(query, 300);
const [results, setResults] = useState([]);

useEffect(() => {
async function search() {
if (!debouncedQuery.trim()) {
setResults([]);
return;
}
const data = await fetch(/api/search?q=${debouncedQuery});
setResults(await data.json());
}
search();
}, [debouncedQuery]);

return (



);
}
`

$3

`tsx
import { useDebounce } from "@usefy/use-debounce";

function FilterPanel() {
const [filters, setFilters] = useState({ category: "all", price: 0 });

// Update immediately on first change, then debounce subsequent changes
const debouncedFilters = useDebounce(filters, 500, { leading: true });

useEffect(() => {
applyFilters(debouncedFilters);
}, [debouncedFilters]);

return (



);
}
`

$3

`tsx
import { useDebounce } from "@usefy/use-debounce";

function AutoSaveEditor() {
const [content, setContent] = useState("");

// Debounce for 1 second, but guarantee save every 5 seconds during continuous typing
const debouncedContent = useDebounce(content, 1000, { maxWait: 5000 });

useEffect(() => {
if (debouncedContent) {
saveToServer(debouncedContent);
}
}, [debouncedContent]);

return (
value={content}
onChange={(e) => setContent(e.target.value)}
placeholder="Start typing... (auto-saves)"
/>
);
}
`

$3

`tsx
import { useDebounce } from "@usefy/use-debounce";

function RegistrationForm() {
const [username, setUsername] = useState("");
const [error, setError] = useState("");
const debouncedUsername = useDebounce(username, 500);

useEffect(() => {
async function checkAvailability() {
if (debouncedUsername.length < 3) {
setError("Username must be at least 3 characters");
return;
}
const response = await fetch(
/api/check-username?u=${debouncedUsername}
);
const { available } = await response.json();
setError(available ? "" : "Username is already taken");
}

if (debouncedUsername) {
checkAvailability();
}
}, [debouncedUsername]);

return (



);
}
`

$3

`tsx
import { useDebounce } from "@usefy/use-debounce";

function FilteredTable() {
const [filters, setFilters] = useState({
search: "",
status: "all",
sortBy: "date",
});

const debouncedFilters = useDebounce(filters, 300);

useEffect(() => {
fetchTableData(debouncedFilters);
}, [debouncedFilters]);

return (



);
}
`

---

TypeScript

This hook is written in TypeScript with full generic support.

`tsx
import { useDebounce, type UseDebounceOptions } from "@usefy/use-debounce";

// Generic type inference
const debouncedString = useDebounce("hello", 300); // string
const debouncedNumber = useDebounce(42, 300); // number
const debouncedObject = useDebounce({ x: 1 }, 300); // { x: number }

// Explicit generic type
interface Filters {
search: string;
category: string;
}
const debouncedFilters = useDebounce(filters, 300);
``

---

Testing

This package maintains comprehensive test coverage to ensure reliability and stability.

$3

📊 View Detailed Coverage Report (GitHub Pages)

$3

Initialization Tests

- Initialize with initial value
- Initialize with different types (string, number, boolean, object, array)
- Use default delay of 500ms

Leading/Trailing Edge Tests

- Update immediately with leading: true
- Do not update immediately with leading: false (default)
- Update on trailing edge with trailing: true (default)
- No update with trailing: false
- Combined leading and trailing options

maxWait Tests

- Force update after maxWait even with continuous changes
- Respect maxWait when delay is longer
- Work correctly with both leading and maxWait

---

License

MIT © mirunamu

This package is part of the usefy monorepo.

---

_{Built with care by the usefy team}