use-debounce

use-debounce is a sub-kilobyte collection of React hooks that bring debouncing and throttling to values and callbacks without ceremony. Its API is intentionally modeled on the lodash/underscore debounce and throttle functions, so the mental model transfers directly, while adapting cleanly to React’s render and effect lifecycle.

The library exposes three hooks — useDebounce for values, useDebouncedCallback for functions, and useThrottledCallback for rate-limiting — each returning control helpers such as cancel, flush, and isPending. It is fully typed, server-rendering friendly, and ships with support for maxWait, leading, and trailing edge behavior.

What You Get

• Three focused hooks: useDebounce (values), useDebouncedCallback (functions), and useThrottledCallback (rate limiting).
• Control helpers on every debounced function — cancel, flush, and isPending — to manage in-flight invocations.
• Configurable timing via maxWait, leading, and trailing options, matching the lodash debounce semantics developers already know.
• First-class TypeScript types and a tree-shakeable, sub-1 KB bundle that is safe for server-side rendering.

Common Use Cases

• Debouncing a search input so a network request only fires after the user stops typing.
• Throttling scroll or resize handlers to avoid excessive re-renders and layout work.
• Flushing a pending debounced save on component unmount so unsaved changes are persisted.

Under The Hood

Architecture — The library is layered around a single core hook. useDebouncedCallback.ts holds all timing logic (timers, maxWait accounting, leading/trailing edges, and the cancel/flush/isPending control functions), memoized with useMemo and kept current across renders via refs. useDebounce.ts builds on it by storing the latest value in a ref and forcing a re-render when the debounced setter fires, while useThrottledCallback.ts is a thin wrapper that simply calls useDebouncedCallback with maxWait equal to the wait interval. index.ts re-exports the three hooks plus their shared TypeScript types, so all public surface derives from one well-tested engine.

Tech Stack — Written entirely in TypeScript targeting React (declared only as a peer dependency, react: '*', with zero runtime dependencies of its own). It builds with microbundle into CommonJS, ESM, and UMD outputs, is tested with Jest and Testing Library under a jsdom environment, and enforces a strict sub-1 KB budget per entry point using size-limit. Linting is handled by ESLint with the standard config and Prettier.

Code Quality — Quality is high for a micro-library. Three substantial test files (useDebounce.test.tsx, useDebouncedCallback.test.tsx, useThrottledCallback.test.tsx, together over 40 KB) cover timing edges, cancellation, flushing, pending state, and server rendering. The public interfaces are fully typed and documented with JSDoc, naming mirrors the familiar lodash vocabulary, and the ref-based implementation carefully avoids stale closures across renders.

API Design — Developer experience is a core strength. Adopting lodash’s debounce/throttle naming and options (maxWait, leading, trailing) means the API is instantly familiar, and returning [value, controls] or a callable augmented with cancel/flush/isPending keeps usage terse. Getting started requires a single import and one hook call, and the README is dense with runnable CodeSandbox examples for each scenario.