@react-hook/debounce

What is @react-hook/debounce?

@react-hook/debounce is a React hook library that provides a simple way to debounce values and functions. Debouncing is a technique used to limit the rate at which a function is executed, ensuring that it is only called after a certain amount of time has passed since the last call. This is particularly useful for optimizing performance in scenarios like handling user input, API calls, and other events that can trigger frequent updates.

What are @react-hook/debounce's main functionalities?

Debouncing a value

This feature allows you to debounce a value, ensuring that the value is only updated after a specified delay. In this example, the `useDebounce` hook is used to debounce the `value` state, and the debounced value is logged to the console.

```javascript
import { useDebounce } from '@react-hook/debounce';

function DebouncedInput() {
  const [value, setValue] = useState('');
  const [debouncedValue] = useDebounce(value, 300);

  useEffect(() => {
    // Perform an action with the debounced value
    console.log(debouncedValue);
  }, [debouncedValue]);

  return (
    <input
      type="text"
      value={value}
      onChange={(e) => setValue(e.target.value)}
    />
  );
}
```

Debouncing a function

This feature allows you to debounce a function, ensuring that the function is only executed after a specified delay. In this example, the `useDebouncedCallback` hook is used to debounce the `handleClick` function, and the debounced function is called when the button is clicked.

```javascript
import { useDebouncedCallback } from '@react-hook/debounce';

function DebouncedButton() {
  const handleClick = () => {
    console.log('Button clicked');
  };

  const debouncedHandleClick = useDebouncedCallback(handleClick, 300);

  return (
    <button onClick={debouncedHandleClick}>
      Click me
    </button>
  );
}
```

Other packages similar to @react-hook/debounce

lodash.debounce

Lodash is a popular utility library that provides a wide range of functions for common programming tasks. The `lodash.debounce` function is a utility that allows you to debounce a function, similar to the `useDebouncedCallback` hook in @react-hook/debounce. However, Lodash does not provide a hook specifically for React, so you would need to integrate it manually into your React components.

use-debounce

The `use-debounce` package provides React hooks for debouncing values and functions. It offers similar functionality to @react-hook/debounce, with hooks like `useDebounce` and `useDebouncedCallback`. The main difference is in the API design and the specific implementation details, but both packages aim to solve the same problem of debouncing in React applications.

react-use

The `react-use` library is a collection of essential React hooks, including hooks for debouncing values and functions. The `useDebounce` and `useDebouncedCallback` hooks in `react-use` provide similar functionality to those in @react-hook/debounce. Additionally, `react-use` offers a wide range of other hooks for various use cases, making it a more comprehensive solution for React developers.

README

---

useDebounce()

npm i @react-hook/debounce

---

A React hook for debouncing setState and other callbacks

Quick Start

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.

export const useDebounce = <State>(
  initialState: State | (() => State),
  wait?: number,
  leading?: boolean
): [State, Dispatch<SetStateAction<State>>]

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.

export const useDebounceCallback = <CallbackArgs extends any[]>(
  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