Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
useDebounce
✓ import { useDebounce } from 'use-debounce';
✗ import useDebounce from 'use-debounce';
const useDebounce = require('use-debounce');
This library is ESM-first since v9. Named imports are required. For CommonJS, explicitly destructure named exports.
useDebouncedCallback
✓ import { useDebouncedCallback } from 'use-debounce';
✗ const debouncedCallback = require('use-debounce').useDebouncedCallback;
import * as useDebounce 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.
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>
);
}
Debug
Known issues
breakingIn 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.fixUpdate bundler configurations or import paths to reference `use-debounce` directly, or specify `.mjs` if targeting a specific module type.
affects: >=10.0.0
breakingThe 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`.fixPass `{ debounceOnServer: true }` in the options object to `useDebounce` or `useDebouncedCallback` if server-side debouncing is required. affects: >=10.0.0
breakingVersion 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.fixEnsure 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.
affects: >=9.0.0 <10.0.0
gotchaPrior 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.fixUpgrade to v10.0.4 or newer to resolve strict mode inconsistencies.
affects: >=10.0.0 <10.0.4
gotchaEarlier 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.fixUpdate to v10.0.5 or a later version to ensure correct `isPending` state management.
affects: >=10.0.0 <10.0.5
Errors
Common errors & fixes
ReferenceError: require is not defined in ES module scope
Attempting to use CommonJS `require()` syntax in an ES Module context after `use-debounce` moved to module support in v9.0.0.
fixUse ES module `import` syntax: `import { useDebounce } from 'use-debounce';` Module not found: Error: Can't resolve 'use-debounce/dist/index.js'
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.
fixUpdate 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
Incorrectly importing `useDebounce` as a default import when it is a named export, or misconfiguring a CommonJS import in a build environment expecting ESM.
fixEnsure `useDebounce` is imported as a named export: `import { useDebounce } from 'use-debounce';` Audit
Dependencies
reactrequiredPeer dependency for React applications.