useDebounce React hook in TypeScript
v1.0.0Added in 1.0.0
React debounce hooks for values and callbacks: search as you type without sending a request on every keystroke.
Type in the search field and watch the two counters: keystrokes climb on every letter, searches only fire once you pause. Press Enter to search at once (flush). Change the delay, add a leading call or a max wait in the playground and type again.
useDebounce is a free React hook in the React hooks and utilities category, written in TypeScript for React 19. It installs as source with npx wingo-ui@latest add use-debounce.
Add to a project
Requirements: React 19, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup
npx wingo-ui@latest add use-debounceUsage
Import useDebouncedCallback from @/hooks/use-debounce.
import { useState } from "react"
import { useDebouncedCallback } from "@/hooks/use-debounce"
export function ListingSearch({ onSearch }: { onSearch: (query: string) => void }) {
const [query, setQuery] = useState("")
const search = useDebouncedCallback(onSearch, 300)
return (
<input
type="search"
value={query}
placeholder="Search listings"
onChange={(event) => {
setQuery(event.target.value)
search(event.target.value)
}}
onKeyDown={(event) => event.key === "Enter" && search.flush()}
/>
)
}API
delaydefault300numberQuiet time in ms before the call runs. 250 to 400 feels instant for search; 0 runs every call at once.
leadingdefaultfalsebooleanAlso run the first call of a burst at once (then wait for the quiet period before the next one).
maxWaitdefault0numberLongest a call may wait while calls keep coming, in ms, for live previews that must update now and then. 0 means no limit.
useDebouncedCallback<A extends unknown[]>(callback: (...args: A) => void, delay?: number, options?: { leading?: boolean; maxWait?: number }) => DebouncedFunction<A>A stable function that runs callback with the latest arguments once calls stop for delay ms. It always calls the latest callback, so there is nothing to memoize. Pending calls are dropped on unmount.
Parts
DebounceOptions
typeThe options of useDebouncedCallback: { leading?: boolean; maxWait?: number }.
DebouncedFunction
typecancel drops the waiting call (clearing a field), flush runs it now (Enter in a search field), pending tells whether one is waiting. Type: ((...args: A) => void) & { cancel(): void; flush(): void; pending(): boolean }.
useDebouncedValue
hookThe value, updated only after it stopped changing for delay ms. Handy as a query key: fetch when the debounced query changes. Signature: <T>(value: T, delay?: number) => T.
Examples
Debounced filter
useDebouncedValue drives the list, so the filter runs once you pause typing.
Autosave with maxWait
Saves 800 ms after typing stops, and every 3 seconds during long bursts.
Leading edge
The first click refreshes right away; rapid clicks after it count as one.
Dependencies
No dependencies beyond React.
Files
- hooks/use-debounce.ts
FAQ
Is the useDebounce hook free?
Yes. The source is free and needs no account: copy it from the Code tab or install it with the CLI.
How do I install useDebounce?
Run npx wingo-ui@latest add use-debounce. With shadcn, run npx shadcn@latest add https://wingo-ui.com/r/use-debounce.json.