use-debounce

https://github.com/xnimorz/use-debounce
Admin
React library providing debounce and throttle hooks with utilities for timing control and...
Tokens:20,426
Snippets:139
Trust Score:9.8
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install use-debounce with Yarn or npm

Source: https://github.com/xnimorz/use-debounce/blob/master/README.md

Install the use-debounce package using either Yarn or npm. The comment indicates the npm command is an alternative to the Yarn command.

```sh
yarn add use-debounce
# or
npm i use-debounce --save
```

--------------------------------

### Control functions and custom equality with useDebounce

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useDebounce.md

Advanced useDebounce example with control functions (cancel, flush, isPending) and a custom equalityFn. Uses leading: true and maxWait: 1500 to control debounce behavior. The applyNow function flushes pending changes or cancels the timer when nothing is pending.

```js
import React, { useState } from 'react';
import { useDebounce } from 'use-debounce';

function FilterPanel() {
  const [filters, setFilters] = useState({ query: '' });
  const [applied, { cancel, flush, isPending }] = useDebounce(
    filters,
    500,
    {
      leading: true,
      maxWait: 1500,
      // Debounce on structural inequality, not reference inequality.
      equalityFn: (left, right) =>
        left.query === right.query,
    }
  );

  // Apply pending filters immediately on demand.
  const applyNow = () => {
    if (isPending()) {
      flush();
    } else {
      cancel(); // nothing pending — just clear any stale timer
    }
  };

  return (
    <div>
      <input
        value={filters.query}
        onChange={(e) => setFilters({ query: e.target.value })}
      />
      <p>Applied query: {applied.query}</p>
      <button onClick={applyNow}>Apply now</button>
    </div>
  );
}
```

--------------------------------

### Check pending state with useDebouncedCallback isPending

Source: https://github.com/xnimorz/use-debounce/blob/master/README.md

Demonstrates the isPending method of useDebouncedCallback, which returns whether there are pending callbacks. The example shows that isPending() is false initially, true after calling the debounced function, and false again after flush().

```javascript
import React, { useCallback } from 'react';

function Component({ text }) {
  const debounced = useDebouncedCallback(
    useCallback(() => {}, []),
    500
  );

  expect(debounced.isPending()).toBeFalsy();
  debounced();
  expect(debounced.isPending()).toBeTruthy();
  debounced.flush();
  expect(debounced.isPending()).toBeFalsy();

  return <span>{text}</span>;
}
```

--------------------------------

### useDebounce

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/index.md

Documentation for the useDebounce hook.

```APIDOC
## useDebounce

### Description
A hook that returns a debounced value and a callback to update it. The value is updated after the specified delay, and the callback can be used to set a new value.

### Signature
```ts
useDebounce<T>(value: T, delay: number, options?: { maxWait?: number; leading?: boolean; trailing?: boolean; equalityFn?: (left: T, right: T) => boolean }): [T, DebouncedState<(value: T) => void>]
```

### Parameters
- **value** (`T`) - Required - The value to debounce.
- **delay** (`number`) - Required - The number of milliseconds to delay.
- **options** (`object`) - Optional - Configuration options:
  - **maxWait** (`number`) - Optional - The maximum time the callback can be delayed.
  - **leading** (`boolean`) - Optional - Invoke on the leading edge.
  - **trailing** (`boolean`) - Optional - Invoke on the trailing edge.
  - **equalityFn** (`(left: T, right: T) => boolean`) - Optional - Function to compare values for equality.

### Returns
- **Array** - A tuple containing the debounced value and a `DebouncedState` callback.

### Example
```ts
import { useDebounce } from 'use-debounce';

const [value, setValue] = useDebounce('initial', 500);
```
```

--------------------------------

### Import useThrottledCallback

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useThrottledCallback.md

Shows how to import the hook from the main package or the documented subpath.

```ts
import { useThrottledCallback } from 'use-debounce';
// README-documented subpath alternative (see package.json exports note in index.md):
import useThrottledCallback from 'use-debounce/useThrottledCallback';
```

--------------------------------

### Catching TypeError('Expected a function') from useDebouncedCallback

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/errors.md

Shows how to catch the TypeError from useDebouncedCallback in consumer code. The error is a plain TypeError thrown synchronously from the hook call. The example checks the error type and message, falls back to a no-op if it matches, and re-throws unexpected errors. Note that useDebounce does not throw this error because its internal callback never receives consumer input.

```js
import React from 'react';
import { useDebouncedCallback } from 'use-debounce';

function Component({ possiblyBrokenHandler }) {
  let debounced;
  try {
    debounced = useDebouncedCallback(possiblyBrokenHandler, 300);
  } catch (err) {
    if (err instanceof TypeError && err.message === 'Expected a function') {
      // Fall back to a no-op so the component still renders.
      debounced = () => undefined;
    } else {
      throw err; // re-raise anything unexpected
    }
  }
  return <button onClick={debounced}>Go</button>;
}

```

--------------------------------

### Options

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/types.md

The Options interface for configuring debounced callbacks, including maxWait and debounceOnServer.

```APIDOC
## `Options`

### Description
Configuration options for the debounced callback, extending `CallOptions`.

### Interface
```ts
export interface Options extends CallOptions {
  /**
   * The maximum time the given function is allowed to be delayed before it's invoked.
   */
  maxWait?: number;
  /**
   * If the setting is set to true, all debouncing and timers will happen on the server side as well
   */
  debounceOnServer?: boolean;
}
```

### Fields
- **maxWait** (`number`, optional) - Maximum time the call may be delayed before it is forced to run. Only active when the key is present (`'maxWait' in options`); effective value is `Math.max(+maxWait || 0, wait)`.
- **debounceOnServer** (`boolean`, optional) - When `true`, debouncing happens on the server side as well (via `setTimeout`). Defaults to `false`; when `false` and `window` is undefined, invoking the debounced function is a no-op returning `undefined`.
- **leading** (`boolean`, optional, inherited) - See `CallOptions`. Default `false`.
- **trailing** (`boolean`, optional, inherited) - See `CallOptions`. Default `true` when the key is present.
- **flushOnExit** (`boolean`, optional, inherited) - See `CallOptions`. Default `false`; effective only when `trailing` is `true`.
```

--------------------------------

### Import useDebounce

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useDebounce.md

Import the useDebounce hook from the 'use-debounce' package.

```ts
import { useDebounce } from 'use-debounce';
```

--------------------------------

### useDebounce options

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/types.md

Options object for the useDebounce hook, including maxWait, leading, trailing, and equalityFn.

```APIDOC
## useDebounce options

### Description
Options object accepted by the `useDebounce` hook to configure debounce behavior.

### Parameters
#### Options Object
- **maxWait** (number) - Optional - Maximum delay before the debounced value is force-applied.
- **leading** (boolean) - Optional - Apply the value immediately on the first change. Default `false`.
- **trailing** (boolean) - Optional - Apply the value after the delay. Default `true`.
- **equalityFn** ((left: T, right: T) => boolean) - Optional - Custom comparator for the change gate. Default `(left, right) => left === right`.
```

--------------------------------

### Advanced useDebouncedCallback with options and control functions

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useDebouncedCallback.md

Uses leading, maxWait, and flushOnExit options. The flush() function can return undefined when nothing is pending, and cancel() is used to cancel a pending save.

```js
import React, { useEffect } from 'react';
import { useDebouncedCallback } from 'use-debounce';

function AutosaveForm({ save, onSaved }) {
  const debounced = useDebouncedCallback(save, 500, {
    leading: true,      // fire the first keystroke immediately
    maxWait: 2000,      // never defer longer than 2 s of continuous typing
    flushOnExit: true,  // persist pending changes on unmount/page close
  });

  // Error handling: flush() can return undefined when nothing is pending.
  useEffect(() => {
    return () => {
      const saved = debounced.flush(); // force pending save on unmount
      if (saved === undefined) {
        console.log('nothing was pending to save');
      }
    };
  }, [debounced]);

  return (
    <form onChange={(e) => debounced(e.target.value)}>
      <textarea defaultValue="" />
      <button type="button" onClick={debounced.cancel}>Cancel pending save</button>
    </form>
  );
}
```

--------------------------------

### Import hooks and types from 'use-debounce'

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/index.md

Shows the canonical root import for the library's public API. Use this to import the three hooks and four types in a TypeScript project.

```typescript
import { useDebounce, useDebouncedCallback, useThrottledCallback } from 'use-debounce';
import type { CallOptions, ControlFunctions, DebouncedState, Options } from 'use-debounce';
```

--------------------------------

### Use leading option with useDebounce

Source: https://github.com/xnimorz/use-debounce/blob/master/README.md

Shows the leading option of useDebounce, which executes the function immediately on the first call and debounces subsequent calls. The trailing option is also mentioned as controlling whether the callback is invoked after the timeout.

```javascript
import React, { useState } from 'react';
import { useDebounce } from 'use-debounce';

export default function Input() {
  const [text, setText] = useState('Hello');
  const [value] = useDebounce(text, 1000, { leading: true });

  // value is updated immediately when text changes the first time,
  // but all subsequent changes are debounced.
  return (
    <div>
      <input
        defaultValue={'Hello'}
        onChange={(e) => {
          setText(e.target.value);
        }}
      />
      <p>Actual value: {text}</p>
      <p>Debounce value: {value}</p>
    </div>
  );
}
```

--------------------------------

### ControlFunctions<ReturnT>

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/types.md

Control functions for managing debounced callbacks: cancel, flush, and isPending.

```APIDOC
## `ControlFunctions<ReturnT>`

### Description
Control functions returned by the debounced callback hook to manage pending invocations.

### Interface
```ts
export interface ControlFunctions<ReturnT> {
  /**
   * Cancel pending function invocations
   */
  cancel: () => void;
  /**
   * Immediately invoke pending function invocations
   */
  flush: () => ReturnT | undefined;
  /**
   * Returns `true` if there are any pending function invocations
   */
  isPending: () => boolean;
}
```

### Members
- **cancel** (`() => void`, required) - Cancels pending invocations, clears the timer and `maxWait` state; may trigger a re-render via `forceUpdate` when a timer was active.
- **flush** (`() => ReturnT | undefined`, required) - Immediately invokes pending invocations, returning the result (via `trailingEdge(Date.now())`). Returns the last result when nothing is pending.
- **isPending** (`() => boolean`, required) - `true` when a timer is scheduled (`!!timerId.current`).
```

--------------------------------

### Hook Configuration Options

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/configuration.md

Configuration options for the use-debounce hooks: useDebouncedCallback, useDebounce, and useThrottledCallback.

```APIDOC
## useDebouncedCallback(func, wait?, options?)

### Description
Creates a debounced version of the provided function. The returned debounced function delays invoking `func` until after `wait` milliseconds have elapsed since the last time the debounced function was invoked, or until the `maxWait` limit is reached. Options control leading/trailing edge invocation, flushing on exit, and server-side behavior.

### Parameters
#### Function Parameters
- **func** (Function) - Required - The function to debounce.
- **wait** (number) - Optional - The number of milliseconds to delay. If omitted, uses `requestAnimationFrame` when `window` exists, otherwise `setTimeout(..., 0)`. Defaults to 0.
- **options** (Options) - Optional - Configuration object.

#### Options Object
- **maxWait** (number) - Optional - Maximum time before a pending call is force-invoked. Effective value is `Math.max(+maxWait || 0, wait)`.
- **leading** (boolean) - Optional - Invoke `func` on the leading edge of the timeout. Default: `false`.
- **trailing** (boolean) - Optional - Invoke `func` on the trailing edge of the timeout. Default: `true`.
- **flushOnExit** (boolean) - Optional - Flush pending invocations on component unmount or when the page/tab becomes hidden. Only effective when `trailing` is `true`. Default: `false`.
- **debounceOnServer** (boolean) - Optional - Enable debouncing on the server (no `window`). When `false` in a server environment, invoking the debounced function is a no-op returning `undefined`. Default: `false`.

#### Internal Parameter
- **forceUpdate** (Dispatch<SetStateAction<object>>) - Optional - Forces a React re-render when `cancel` clears an active timer or when a leading-edge-only timer expires. Passed by `useDebounce`; consumers rarely need it.

### Returns
A debounced version of `func` with methods `cancel`, `flush`, `isPending`, and `isLeading` (not explicitly documented in source but implied by usage).

### Notes
- The `wait` parameter is normalized via `wait = +wait || 0`.
- The `trailing` option defaults to `true` unless explicitly set to `false`.
- The `flushOnExit` option is only effective when `trailing` is `true`.
- When `debounceOnServer` is `false` and there is no `window`, invoking the debounced function is a no-op returning `undefined`.
```

```APIDOC
## useDebounce(value, delay, options?)

### Description
Returns a debounced version of the `value` that only updates after `delay` milliseconds have passed without the value changing. The options object controls the debounce behavior, including a custom equality function to determine when the value has changed.

### Parameters
#### Function Parameters
- **value** (T) - Required - The value to debounce.
- **delay** (number) - Required - The debounce delay in milliseconds. No default.
- **options** (object) - Optional - Configuration object.

#### Options Object
- **maxWait** (number) - Optional - Maximum delay before the debounced value is forced through. Delegates to `Options.maxWait` semantics.
- **leading** (boolean) - Optional - Apply the value immediately on the first change within a wait window. Default: `false`.
- **trailing** (boolean) - Optional - Apply the value after the delay elapses. Default: `true`.
- **equalityFn** ((left: T, right: T) => boolean) - Optional - Comparator that decides whether an incoming value differs from the previously handled one; a cycle is started only on inequality. Default: `(left, right) => left === right`.

### Returns
The debounced value.

### Notes
- The options object is forwarded directly to `useDebouncedCallback`, so undocumented keys such as `flushOnExit` are also read by the underlying engine even though they are not part of the declared inline type.
```

```APIDOC
## useThrottledCallback(func, wait, options?)

### Description
Creates a throttled version of the provided function. The returned throttled function invokes `func` at most once per `wait` milliseconds, with leading and trailing edge invocation controlled by options. Throttling is implemented by setting `maxWait` equal to `wait` in the underlying `useDebouncedCallback`.

### Parameters
#### Function Parameters
- **func** (Function) - Required - The function to throttle.
- **wait** (number) - Required - The throttle interval in milliseconds. No default.
- **options** (CallOptions) - Optional - Configuration object.

#### Options Object
- **leading** (boolean) - Optional - Invoke on the leading edge of the throttle window. Default: `true`.
- **trailing** (boolean) - Optional - Invoke on the trailing edge of the throttle window. Default: `true`.
- **flushOnExit** (boolean) - Optional - Flush a pending invocation on unmount/hidden page. Default: `false`.

### Returns
A throttled version of `func`.

### Notes
- There is no `maxWait` option; it is fixed internally to `wait`.
- The `leading` default is `true`, unlike `useDebouncedCallback`.
```

--------------------------------

### useDebouncedCallback

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/index.md

Documentation for the useDebouncedCallback hook.

```APIDOC
## useDebouncedCallback

### Description
Creates a debounced callback function that delays invoking the provided function until after `wait` milliseconds have elapsed since the last time the debounced function was invoked. Returns a `DebouncedState` object with control functions.

### Signature
```ts
useDebouncedCallback<T extends (...args: any) => ReturnType<T>>(func: T, wait?: number, options?: Options, forceUpdate?: Dispatch<SetStateAction<object>>): DebouncedState<T>
```

### Parameters
- **func** (`T`) - Required - The function to debounce.
- **wait** (`number`) - Optional - The number of milliseconds to delay.
- **options** (`Options`) - Optional - Configuration options (see `Options` type).
- **forceUpdate** (`Dispatch<SetStateAction<object>>`) - Optional - A dispatch function to force a re-render.

### Returns
- **DebouncedState<T>** - An object with the debounced function and control functions (`cancel`, `flush`, `isPending`).

### Example
```ts
import { useDebouncedCallback } from 'use-debounce';

const debounced = useDebouncedCallback((value) => {
  console.log(value);
}, 500);

debounced('hello');
```
```

--------------------------------

### Import useThrottledCallback (default)

Source: https://github.com/xnimorz/use-debounce/blob/master/README.md

Default import for the throttled callback hook from the use-debounce package.

```javascript
import useThrottledCallback from 'use-debounce/useThrottledCallback';
```

--------------------------------

### CallOptions

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/types.md

The CallOptions interface defines optional settings for debounced and throttled callbacks, including leading/trailing edge invocation and flushing on exit.

```APIDOC
## CallOptions

### Description
Options for controlling the invocation timing of debounced or throttled callbacks.

### Fields
- **leading** (boolean) - Optional - Controls if the function should be invoked on the leading edge of the timeout. Defaults to `false` in `useDebouncedCallback`, to `true` in `useThrottledCallback`.
- **trailing** (boolean) - Optional - Controls if the function should be invoked on the trailing edge of the timeout. Defaults to `true`.
- **flushOnExit** (boolean) - Optional - Controls if the function should be invoked when the React component unmounts or the page is closed. This is usually desirable whenever `func` has persistent side-effects such as persists data. NOTE: If the callback calls `fetch()`, you usually also want to specify the `keepalive=true` option for `fetch()` so it can finish in the background after the page is closed. This option has no effect if `trailing == false`.
```

--------------------------------

### Import useDebouncedCallback

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useDebouncedCallback.md

Import the hook from the 'use-debounce' package.

```typescript
import { useDebouncedCallback } from 'use-debounce';
```

--------------------------------

### Options and CallOptions interfaces

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useDebouncedCallback.md

The Options interface extends CallOptions and adds maxWait and debounceOnServer. CallOptions defines leading, trailing, and flushOnExit flags.

```typescript
export interface Options extends CallOptions {
  /**
   * The maximum time the given function is allowed to be delayed before it's invoked.
   */
  maxWait?: number;
  /**
   * If the setting is set to true, all debouncing and timers will happen on the server side as well
   */
  debounceOnServer?: boolean;
}
```

```typescript
export interface CallOptions {
  leading?: boolean;   // invoke on the leading edge of the timeout
  trailing?: boolean;  // invoke on the trailing edge of the timeout
  flushOnExit?: boolean; // invoke when the component unmounts or the page closes
}
```

--------------------------------

### CallOptions interface

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useThrottledCallback.md

Defines the options for the throttled callback: leading, trailing, and flushOnExit. These control when the function is invoked relative to the timeout and on unmount/page close.

```ts
// CallOptions (src/useDebouncedCallback.ts:9-17, re-exported):
export interface CallOptions {
  leading?: boolean;    // invoke on the leading edge of the timeout
  trailing?: boolean;   // invoke on the trailing edge of the timeout
  flushOnExit?: boolean;// invoke when the component unmounts or page closes
}
```

--------------------------------

### useThrottledCallback

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/index.md

Documentation for the useThrottledCallback hook.

```APIDOC
## useThrottledCallback

### Description
Creates a throttled callback that ensures the function is called at most once per `wait` milliseconds. It delegates to `useDebouncedCallback` with `maxWait` set to `wait`.

### Signature
```ts
useThrottledCallback<T extends (...args: any) => ReturnType<T>>(func: T, wait: number, { leading = true, trailing = true, flushOnExit = false }: CallOptions = {}): DebouncedState<T>
```

### Parameters
- **func** (`T`) - Required - The function to throttle.
- **wait** (`number`) - Required - The number of milliseconds to throttle.
- **options** (`CallOptions`) - Optional - Configuration options:
  - **leading** (`boolean`) - Optional - Invoke on the leading edge (default `true`).
  - **trailing** (`boolean`) - Optional - Invoke on the trailing edge (default `true`).
  - **flushOnExit** (`boolean`) - Optional - Flush pending calls on unmount (default `false`).

### Returns
- **DebouncedState<T>** - An object with the throttled function and control functions.

### Example
```ts
import { useThrottledCallback } from 'use-debounce';

const throttled = useThrottledCallback((value) => {
  console.log(value);
}, 1000);

throttled('hello');
```
```

--------------------------------

### Options interface with maxWait and debounceOnServer

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/types.md

Defines the options object for useDebouncedCallback. Extends CallOptions. maxWait forces invocation after a maximum delay; debounceOnServer enables server-side debouncing. Defaults: debounceOnServer false, leading false, trailing true when present, flushOnExit false.

```ts
export interface Options extends CallOptions {
  /**
   * The maximum time the given function is allowed to be delayed before it's invoked.
   */
  maxWait?: number;
  /**
   * If the setting is set to true, all debouncing and timers will happen on the server side as well
   */
  debounceOnServer?: boolean;
}
```

--------------------------------

### useDebouncedCallback with maxWait and cancel, and useDebounce API

Source: https://github.com/xnimorz/use-debounce/blob/master/README.md

Shows how to use the maxWait option and the cancel method with useDebouncedCallback, and the equivalent API for useDebounce. The maxWait option limits the maximum delay before the function is invoked, and cancel() cancels the pending debounce cycle.

```javascript
import React, { useState } from 'react';
import ReactDOM from 'react-dom';
import { useDebouncedCallback } from 'use-debounce';

function Input({ defaultValue }) {
  const [value, setValue] = useState(defaultValue);
  const debounced = useDebouncedCallback(
    (value) => {
      setValue(value);
    },
    500,
    // The maximum time func is allowed to be delayed before it's invoked:
    { maxWait: 2000 }
  );

  // you should use `e => debounced(e.target.value)` as react works with synthetic events
  return (
    <div>
      <input
        defaultValue={defaultValue}
        onChange={(e) => debounced(e.target.value)}
      />
      <p>Debounced value: {value}</p>
      <button onClick={debounced.cancel}>Cancel Debounce cycle</button>
    </div>
  );
}

const rootElement = document.getElementById('root');
ReactDOM.render(<Input defaultValue="Hello world" />, rootElement);
```

```js
const [value, {cancel, isPending, flush}] = useDebounce(valueToDebounce);
...
cancel() // cancels pending debounce request
isPending() // returns if there is a pending debouncing request
flush() // immediately flushes pending request
```

--------------------------------

### Basic value debouncing with useDebounce

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useDebounce.md

Basic usage of useDebounce to debounce a text input value by 1000ms. The debounced value updates after the delay, while the actual value updates immediately.

```js
import React, { useState } from 'react';
import { useDebounce } from 'use-debounce';

export default function Input() {
  const [text, setText] = useState('Hello');
  const [debouncedValue] = useDebounce(text, 1000);

  return (
    <div>
      <input
        defaultValue="Hello"
        onChange={(e) => setText(e.target.value)}
      />
      <p>Actual value: {text}</p>
      <p>Debounced value: {debouncedValue}</p>
    </div>
  );
}
```

--------------------------------

### useDebounce<T>(value, delay, options?)

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useDebounce.md

A React hook that returns a debounced value and a stateful callback. The value is updated only after the specified delay, and the component re-renders when the debounced value changes.

```APIDOC
## useDebounce<T>(value, delay, options?)

### Description
Debounces a value (e.g., an input's text) rather than a callback. It keeps an internal "active" value, updates it only after the delay, and re-renders the component when the debounced value lands.

### Import
```ts
import { useDebounce } from 'use-debounce';
```

### Signature
```ts
export default function useDebounce<T>(
  value: T,
  delay: number,
  options?: {
    maxWait?: number;
    leading?: boolean;
    trailing?: boolean;
    equalityFn?: (left: T, right: T) => boolean;
  }
): [T, DebouncedState<(value: T) => void>]
```

### Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `value` | `T` | yes | — | The possibly-fresh value to debounce. Compared against the previously passed value using `equalityFn`; if they differ, a debounce cycle for `value` is started. |
| `delay` | `number` | yes | — | Debounce delay in milliseconds. Unlike `useDebouncedCallback`, this parameter is required here. |
| `options` | `{ maxWait?: number; leading?: boolean; trailing?: boolean; equalityFn?: (left: T, right: T) => boolean }` | no | `{}` | Configuration options for the debounce behavior. |

### Options Field Details

| Field | Type | Default | Description |
|---|---|---|---|
| `maxWait` | `number` | inactive unless provided | Maximum time the value may stay un-applied before it is forced through. Clamped to be at least `delay` (`Math.max(+maxWait || 0, wait)` in `src/useDebouncedCallback.ts:171`). |
| `leading` | `boolean` | `false` | Apply the value immediately on the first change; subsequent changes within the delay are debounced. |
| `trailing` | `boolean` | `true` | Apply the value after the delay elapses. |
| `equalityFn` | `(left: T, right: T) => boolean` | `(left, right) => left === right` | Comparator deciding whether the incoming `value` differs from the previously handled one. Used to skip debouncing when the value "hasn't changed". |

### Return Value
Returns a tuple `[T, DebouncedState<(value: T) => void>]` where the first element is the debounced value and the second is a stateful callback to update the value.
```

--------------------------------

### useThrottledCallback signature

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useThrottledCallback.md

The hook's type signature, copied verbatim from the source file. It accepts a function, a wait time in milliseconds, and optional CallOptions with defaults leading=true, trailing=true, flushOnExit=false.

```ts
export default function useThrottledCallback<
  T extends (...args: any) => ReturnType<T>,
>(
  func: T,
  wait: number,
  { leading = true, trailing = true, flushOnExit = false }: CallOptions = {}
): DebouncedState<T>
```

--------------------------------

### Basic debounced callback with useDebouncedCallback

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useDebouncedCallback.md

Debounces a state update by 400 ms. The returned function is used as an onChange handler, passing the input value to the debounced callback.

```js
import React, { useState } from 'react';
import { useDebouncedCallback } from 'use-debounce';

function SearchInput({ defaultValue }) {
  const [value, setValue] = useState(defaultValue);

  // Debounce a state update by 400 ms.
  const debounced = useDebouncedCallback(
    (next) => setValue(next),
    400
  );

  return (
    <input
      defaultValue={defaultValue}
      onChange={(e) => debounced(e.target.value)}
    />
  );
}
```

--------------------------------

### Import useThrottledCallback (named)

Source: https://github.com/xnimorz/use-debounce/blob/master/README.md

Named import for the throttled callback hook from the use-debounce package.

```javascript
import { useThrottledCallback } from 'use-debounce';
```

--------------------------------

### Trailing-only throttling with error handling

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useThrottledCallback.md

Uses trailing-only throttling (leading: false, trailing: true) to limit token refresh calls to at most once per 5 minutes. The returned callback returns undefined when an invocation is throttled or still pending, which is checked in the click handler.

```js
import React from 'react';
import { useThrottledCallback } from 'use-debounce';

function TokenRefresher({ renewToken, onError }) {
  // Leading edge off: calls during the interval are folded into a single
  // trailing invocation, but never more than one per 5 minutes.
  const throttled = useThrottledCallback(
    async () => {
      try {
        await renewToken();
      } catch (err) {
        onError(err);
      }
    },
      300000,
      { leading: false, trailing: true }
  );

  const handleClick = () => {
    const res = throttled();
    if (res === undefined) {
      // No invocation has completed (yet) — throttled or pending.
      console.log('token refresh throttled or still pending');
    }
  };

  return <button onClick={handleClick}>Manual token refresh</button>;
}
```

--------------------------------

### Implementation of useThrottledCallback

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useThrottledCallback.md

The entire implementation delegates to useDebouncedCallback with maxWait set to wait, which turns debouncing into throttling.

```typescript
return useDebouncedCallback(func, wait, {
  maxWait: wait,
  leading,
  trailing,
  flushOnExit,
});
```

--------------------------------

### useDebounce function signature

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useDebounce.md

Signature of the useDebounce hook. The options parameter is an anonymous inline type with fields maxWait, leading, trailing, and equalityFn. The delay parameter is required, unlike in useDebouncedCallback.

```ts
export default function useDebounce<T>(
  value: T,
  delay: number,
  options?: {
    maxWait?: number;
    leading?: boolean;
    trailing?: boolean;
    equalityFn?: (left: T, right: T) => boolean;
  }
): [T, DebouncedState<(value: T) => void>]
```

--------------------------------

### CallOptions interface definition

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/types.md

Defines the CallOptions interface with optional leading, trailing, and flushOnExit flags. Defaults: leading false in useDebouncedCallback, true in useThrottledCallback; trailing true; flushOnExit has no effect when trailing is false.

```typescript
export interface CallOptions {
  /**
   * Controls if the function should be invoked on the leading edge of the timeout.
   */
  leading?: boolean;
  /**
   * Controls if the function should be invoked on the trailing edge of the timeout.
   */
  trailing?: boolean;
  /**
   * Controls if the function should be invoked when the React component unmounts or
   * the page is closed. This is usually desirable whenever `func` has persistent side-effects
   * such as persists data.
   *
   * NOTE: If the callback calls `fetch()`, you usually also want to specify the `keepalive=true`
   * option for `fetch()` so it can finish in the background after the page is closed.
   *
   * This option has no effect if `trailing == false`.
   */
  flushOnExit?: boolean;
}
```

--------------------------------

### Flush debounced callback on unmount with useDebouncedCallback

Source: https://github.com/xnimorz/use-debounce/blob/master/README.md

Uses the flush method of useDebouncedCallback to manually invoke the callback when the component unmounts, ensuring pending data fetches are executed. The callback is debounced with a 500ms delay and a maxWait of 2000ms.

```javascript
import React, { useState } from 'react';
import { useDebouncedCallback } from 'use-debounce';

function InputWhichFetchesSomeData({ defaultValue, asyncFetchData }) {
  const debounced = useDebouncedCallback(
    (value) => {
      asyncFetchData;
    },
    500,
    { maxWait: 2000 }
  );

  // When the component goes to be unmounted, we will fetch data if the input has changed.
  useEffect(
    () => () => {
      debounced.flush();
    },
    [debounced]
  );

  return (
    <input
      defaultValue={defaultValue}
      onChange={(e) => debounced(e.target.value)}
    />
  );
}
```

--------------------------------

### useThrottledCallback

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/api-reference/useThrottledCallback.md

Creates a throttled function that invokes the provided callback at most once per wait milliseconds. It is a wrapper around useDebouncedCallback with maxWait set to wait, ensuring the callback is not delayed past the interval. Supports leading and trailing edge invocation and optional flush on unmount or page close.

```APIDOC
## useThrottledCallback

### Description
Creates a throttled function that invokes the provided callback at most once per `wait` milliseconds. It is a wrapper around `useDebouncedCallback` with `maxWait` set to `wait`, ensuring the callback is not delayed past the interval. Supports leading and trailing edge invocation and optional flush on unmount or page close.

### Import
```ts
import { useThrottledCallback } from 'use-debounce';
// README-documented subpath alternative:
import useThrottledCallback from 'use-debounce/useThrottledCallback';
```

### Signature
```ts
export default function useThrottledCallback<
  T extends (...args: any) => ReturnType<T>,
>(
  func: T,
  wait: number,
  { leading = true, trailing = true, flushOnExit = false }: CallOptions = {}
): DebouncedState<T>
```

### Parameters
- **func** (`T`) - Required - The function to throttle. Must be a function that returns a value.
- **wait** (`number`) - Required - The number of milliseconds to throttle invocations to. The function will be called at most once per this interval.
- **options** (`CallOptions`) - Optional - Configuration object with the following properties:
  - **leading** (`boolean`) - Optional - Defaults to `true`. If `true`, invoke the function on the leading edge of the timeout (immediately on first call).
  - **trailing** (`boolean`) - Optional - Defaults to `true`. If `true`, invoke the function on the trailing edge of the timeout (after the wait period).
  - **flushOnExit** (`boolean`) - Optional - Defaults to `false`. If `true`, invoke the function when the component unmounts or the page closes.

### Return Value
Returns a `DebouncedState<T>` object, which is a callable function with the same signature as the original function, plus control functions. The callable function returns the result of the original function or `undefined` if the call was throttled.

### Type Definitions
```ts
// CallOptions
export interface CallOptions {
  leading?: boolean;    // invoke on the leading edge of the timeout
  trailing?: boolean;   // invoke on the trailing edge of the timeout
  flushOnExit?: boolean;// invoke when the component unmounts or page closes
}

// DebouncedState
export interface DebouncedState<T extends (...args: any) => ReturnType<T>>
  extends ControlFunctions<ReturnType<T>> {
  (...args: Parameters<T>): ReturnType<T> | undefined;
}
```

### Notes
- Unlike `useDebouncedCallback`, the `leading` option defaults to `true` in this hook.
- The hook is a pure configuration wrapper over `useDebouncedCallback` with `maxWait` set to `wait`.
```

--------------------------------

### ControlFunctions interface with cancel, flush, isPending

Source: https://github.com/xnimorz/use-debounce/blob/master/_autodocs/types.md

Defines the control functions returned by useDebouncedCallback. cancel clears pending invocations, flush immediately invokes pending work, and isPending reports whether a timer is scheduled.

```ts
export interface ControlFunctions<ReturnT> {
  /**
   * Cancel pending function invocations
   */
  cancel: () => void;
  /**
   * Immediately invoke pending function invocations
   */
  flush: () => ReturnT | undefined;
  /**
   * Returns `true` if there are any pending function invocations
   */
  isPending: () => boolean;
}
```

--------------------------------

### Debounce a simple value with useDebounce

Source: https://github.com/xnimorz/use-debounce/blob/master/README.md

Debounce a simple value with useDebounce. The hook compares previous and next values using shallow equal, so setting an object {} will trigger the debounce timer. For object comparison, use useDebouncedCallback instead.

```javascript
import React, { useState } from 'react';
import { useDebounce } from 'use-debounce';

export default function Input() {
  const [text, setText] = useState('Hello');
  const [value] = useDebounce(text, 1000);

  return (
    <div>
      <input
        defaultValue={'Hello'}
        onChange={(e) => {
          setText(e.target.value);
        }}
      />
      <p>Actual value: {text}</p>
      <p>Debounce value: {value}</p>
    </div>
  );
}
```
Tokens:
Raw