React Debounce Hooks (use-debounce)

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax in an ES Module context after `use-debounce` moved to module support in v9.0.0.
  fix Use ES module `import` syntax: `import { useDebounce } from 'use-debounce';`

• Module not found: Error: Can't resolve 'use-debounce/dist/index.js'

  cause Your build configuration or explicit import path is still referencing the old CommonJS entry point (`dist/index.js`) after it changed to `dist/index.cjs` in v9.0.0.
  fix Update your import paths to `use-debounce` (preferred for modern bundlers) or `use-debounce/dist/index.cjs` if explicitly targeting CommonJS.

• TypeError: (0 , _useDebounce.useDebounce) is not a function

  cause Incorrectly importing `useDebounce` as a default import when it is a named export, or misconfiguring a CommonJS import in a build environment expecting ESM.
  fix Ensure `useDebounce` is imported as a named export: `import { useDebounce } from 'use-debounce';`

Warnings

• breaking In v10.0.0, the ESM build output path was changed from `index.modern.js` to `index.mjs`. Projects directly referencing internal module paths in their build pipelines may require adjustment.
  Fix: Update bundler configurations or import paths to reference `use-debounce` directly, or specify `.mjs` if targeting a specific module type.
• breaking The v10.0.0 release introduced the `debounceOnServer` option, which defaults to `false`. This means debounced callbacks no longer execute on the server by default. If your application relies on server-side debouncing, you must explicitly set `debounceOnServer: true`.
  Fix: Pass `{ debounceOnServer: true }` in the options object to `useDebounce` or `useDebouncedCallback` if server-side debouncing is required.
• breaking Version 9.0.0 changed the CommonJS entry point path from `dist/index.js` to `dist/index.cjs`. This impacts projects using `require()` or build tools configured for the old path.
  Fix: Ensure your build system or direct `require` statements correctly resolve to the `use-debounce` package root, letting Node.js resolve the correct entry point (preferred), or update explicit paths to `dist/index.cjs` if necessary.
• gotcha Prior to v10.0.4, `useDebounce` and `useDebouncedCallback` exhibited incorrect behavior when both `leading` and `trailing` options were set to `true` specifically within React Strict Mode.
  Fix: Upgrade to v10.0.4 or newer to resolve strict mode inconsistencies.
• gotcha Earlier versions (prior to v10.0.5) had a bug where the `isPending` state might not reset correctly if the tracked value for `useDebounce` had not changed, leading to potentially stale UI indications.
  Fix: Update to v10.0.5 or a later version to ensure correct `isPending` state management.

Install

• npm install use-debounce npm
• yarn add use-debounce yarn
• pnpm add use-debounce pnpm

Imports

• useDebounce
  wrong:

  import useDebounce from 'use-debounce';
  const useDebounce = require('use-debounce');

  correct:

  import { useDebounce } from 'use-debounce';

  This library is ESM-first since v9. Named imports are required. For CommonJS, explicitly destructure named exports.
• useDebouncedCallback
  wrong:

  const debouncedCallback = require('use-debounce').useDebouncedCallback;
  import * as useDebounce from 'use-debounce';

  correct:

  import { useDebouncedCallback } from 'use-debounce';

  As a named export, ensure you use destructuring for CommonJS or named import syntax for ESM.
• DebounceOptions

  import type { DebounceOptions } from 'use-debounce';

  Type import for configuring debounce behavior.

Quickstart

Demonstrates how to debounce a React state value using the `useDebounce` hook, updating a displayed value only after a specified delay.

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

export default function InputExample() {
  const [text, setText] = useState('Hello');
  // Debounce the 'text' value with a 1000ms delay
  const [debouncedValue] = useDebounce(text, 1000);

  return (
    <div>
      <h2>Debounced Input Example</h2>
      <input
        defaultValue={'Hello'}
        onChange={(e) => {
          setText(e.target.value);
        }}
        style={{ padding: '8px', fontSize: '16px' }}
      />
      <p><b>Actual value:</b> {text}</p>
      <p><b>Debounced value:</b> {debouncedValue}</p>
      <p style={{ fontSize: '0.8em', color: '#666' }}>
        The 'Debounced value' updates 1 second after you stop typing.
      </p>
    </div>
  );
}