useDebounce()
npm i @react-hook/debounce
A React hook for debouncing setState and other callbacks
## Quick Start
```jsx harmony
import {useDebounce, useDebounceCallback} from '@react-hook/debounce'
const Component = (props) => {
// at a basic level, used just like useState
const [value, setValue] = useDebounce('initialValue')
}
const useMyCallback = (initialState, wait, leading) => {
// this is the same code useDebounce() uses to debounce setState
const [state, setState] = useState(initialState)
return [state, useDebounceCallback(setState, wait, leading)]
}
```
## API
### useDebounce(initialState, wait?, leading?)
A hook that acts just like `React.useState`, but with a `setState` function
that is only invoked after the `wait` time in `ms` has been exceeded between
calls.
```ts
export const useDebounce = (
initialState: State | (() => State),
wait?: number,
leading?: boolean
): [State, Dispatch>]
```
#### Options
| Property | Type | Default | Description |
| ------------ | ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| initialState | `State \| (() => State)` | | The initial state provided to `React.useState` |
| wait | `number` | `100` | The amount of time in `ms` you want to wait after the latest call before setting a new state. |
| leading | `boolean` | `false` | Calls `setState` on the leading edge (right away). When `false`, `setState` will not be called until the next frame is due |
#### Returns `[state, setStateDebounced, setStateImmediate]`
| Variable | Type | Description |
| ----------------- | ---------- | ------------------------------------------ |
| state | `State` | The current value in state |
| setStateDebounced | `Function` | A debounced `setState` callback |
| setStateImmediate | `Function` | The regular, immediate `setState` callback |
Note: Using `setStateImmediate` does not cancel a queued `setStateDebounced` calls,
i.e., the `setStateDebounced` will still take effect once its wait time is over.
If needed, cancelling behavior could typically still be achieved by calling both
`setStateImmediate` and `setStateDebounced` with the same value.
---
### useDebounceCallback(callback, wait?, leading?)
A hook that will invoke its callback only after `wait` time in `ms` has been
exceeded between calls.
```ts
export const useDebounceCallback = (
callback: (...args: CallbackArgs) => void,
wait = 100,
leading = false
): ((...args: CallbackArgs) => void)
```
#### Options
| Property | Type | Default | Description |
| -------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| callback | `(...args: CallbackArgs) => void` | | This is the callback you want to debounce. You need to wrap closures/unstable callbacks in `useCallback()` so that they are stable, otherwise throttling will break between renders. |
| wait | `number` | `100` | Defines the amount of time you want `setState` to wait after the last received action before executing |
| leading | `boolean` | `false` | Calls `setState` on the leading edge (right away). When `false`, `setState` will not be called until the next frame is due |
#### Returns `debouncedCallback`
| Variable | Type | Description |
| ----------------- | --------------------------------- | ------------------------------------ |
| debouncedCallback | `(...args: CallbackArgs) => void` | A debounced version of your callback |
## LICENSE
MIT