# useDebouncedValue

Returns `value`, but only after it has stopped changing for `delayMs`. Starts as `value` (also on the server), then lags behind while it changes.

With Chinese, Japanese, or Korean input, the text changes in steps while a character is composed. Keep the input's own state updating, and debounce a separate query that you set only when `e.nativeEvent.isComposing` is false and in `onCompositionEnd`.

## Import

```ts
import { useDebouncedValue } from '@vincent.ri/react-tils'
// or only this hook
import { useDebouncedValue } from '@vincent.ri/react-tils/useDebouncedValue'
```

## Usage

```ts
const [query, setQuery] = useState('')
const debouncedQuery = useDebouncedValue(query, 300)
const results = useSearch(debouncedQuery) // your data-fetching hook
return <input value={query} onChange={(e) => setQuery(e.target.value)} />
```

## When to use it

Deriving a request from fast-changing state, e.g. fetching search results for a query typed into a controlled input.

## When not to

You have an event handler to debounce instead of a value; use `useDebouncedCallback`, which also has `cancel` and `flush`. To keep typing responsive while rendering something expensive, use React's `useDeferredValue`, which has no fixed delay.

## API

```ts
function useDebouncedValue<T>(value: T, delayMs: number): T
```

| Parameter | Description |
| --- | --- |
| `value` | The value to debounce. Compared with `Object.is`: pass a primitive or a memoized object. A new array or object every render re-renders every `delayMs` forever. |
| `delayMs` | How long `value` must stay unchanged. |

## Browser support

Works in all modern browsers.

## Coming from another library?

Other libraries call this `useDebounce`, `useDebounceValue`.

---

99 B minified and brotlied
Source: https://github.com/vincentri/react-tils/blob/main/src/useDebouncedValue.ts
Docs page: https://vincentri.github.io/react-tils/hooks/useDebouncedValue/
Previous: [useDebouncedCallback](https://vincentri.github.io/react-tils/hooks/useDebouncedCallback.md)
Next: [useThrottledCallback](https://vincentri.github.io/react-tils/hooks/useThrottledCallback.md)