# useDebounce

> React debounce hooks for values and callbacks: search as you type without sending a request on every keystroke.

- Type: React hook (Hooks & Utilities)
- Access: Free (the source is open to everyone)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add use-debounce`
- Docs: https://wingo-ui.com/components/use-debounce

## Interaction

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.

## Installation

```bash
npx wingo-ui@latest add use-debounce
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/use-debounce.json`

Files:

- `hooks/use-debounce.ts`

## Usage

```tsx
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

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `delay?` | `number` | `300` | Quiet time in ms before the call runs. 250 to 400 feels instant for search; 0 runs every call at once. |
| `leading?` | `boolean` | `false` | Also run the first call of a burst at once (then wait for the quiet period before the next one). |
| `maxWait?` | `number` | `0` | Longest 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 (type)

The options of useDebouncedCallback: { leading?: boolean; maxWait?: number }.

### DebouncedFunction (type)

cancel 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 (hook)

The 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.

## See also

- [Search Input](https://wingo-ui.com/components/search-input) ([Markdown](https://wingo-ui.com/components/search-input.md))
- [Text match](https://wingo-ui.com/components/text-match) ([Markdown](https://wingo-ui.com/components/text-match.md))
- [useShortcut](https://wingo-ui.com/components/use-shortcut) ([Markdown](https://wingo-ui.com/components/use-shortcut.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))

---

Canonical: https://wingo-ui.com/components/use-debounce
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt