Registry / web-framework / react-debounce-input

react-debounce-input

library3.3.0jsnpmunverified

react-debounce-input is a React component that provides debounced `onChange` functionality for HTML input elements (like `<input>` or `<textarea>`) or any custom React component that follows the `value`/`onChange` prop pattern. It prevents excessive re-renders, state updates, or API calls during rapid user input by delaying the `onChange` callback until a specified `debounceTimeout` has elapsed since the last change. The current stable version is `3.3.0`, which added official React 18 support. The package maintains an active release cadence, addressing bug fixes, enhancing features (e.g., TypeScript support since v3.2.0, `inputRef` in v3.1.0), and keeping dependencies updated. Its primary differentiator is its straightforward, drop-in usability, enabling developers to easily integrate debouncing without writing custom logic, offering a simple alternative to more complex form libraries.

web-framework

npm install react-debounce-input

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-DEBOUNCE-INP

react-debounce-input

web-frameworkjavascriptv3.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DebounceInput

✓ import { DebounceInput } from 'react-debounce-input';

✗ import DebounceInput from 'react-debounce-input';

The main component is provided as a named export. Attempting a default import will result in an undefined value at runtime.

DebounceInputProps

✓ import type { DebounceInputProps } from 'react-debounce-input';

This type import allows for type-checking props when extending or creating wrappers around the DebounceInput component in TypeScript projects.

DebounceInput (CommonJS)

✓ const { DebounceInput } = require('react-debounce-input');

This CommonJS `require` syntax is for older Node.js environments or legacy build setups. Modern React applications typically use ESM `import` statements.

This quickstart demonstrates how to use `DebounceInput` with a functional React component, setting a minimum length and a debounce timeout. It also showcases state management for the debounced value.

import React, { useState } from 'react'; import ReactDOM from 'react-dom'; import { DebounceInput } from 'react-debounce-input'; interface AppState { value: string; } const App: React.FC = () => { const [value, setValue] = useState<string>(''); const handleChange = (event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => { console.log('Debounced onChange triggered:', event.target.value); setValue(event.target.value); }; return ( <div style={{ fontFamily: 'sans-serif', padding: '20px' }}> <h1>React Debounce Input Demo</h1> <label htmlFor="debounced-input" style={{ display: 'block', marginBottom: '10px' }}> Type here (min 2 chars, 300ms debounce): </label> <DebounceInput id="debounced-input" minLength={2} debounceTimeout={300} onChange={handleChange} placeholder="Start typing..." style={{ width: '300px', padding: '8px', fontSize: '16px', border: '1px solid #ccc', borderRadius: '4px' }} /> <p style={{ marginTop: '20px', fontSize: '1.1em' }}> Current debounced value: <strong>{value}</strong> </p> <p style={{ color: '#666' }}> This input will only update the displayed value after 300ms of no typing and when at least 2 characters have been entered. Pressing Enter will also force a notification (by default). </p> </div> ); }; const appRoot = document.getElementById('app-root') || document.createElement('div'); appRoot.id = 'app-root'; document.body.appendChild(appRoot); ReactDOM.render(<App />, appRoot);

Debug

Known issues

breakingReact versions older than 15.3.0 are no longer supported due to a major version update.

fix

Upgrade your React project to version 15.3.0 or higher. If you must support older React versions, use `react-debounce-input@2.x`.

affects: >=3.0.0

gotchaSetting `debounceTimeout` to `-1` disables automatic debounced notifications completely. The `onChange` event will only be triggered when the `Enter` key is pressed.

fix

To enable automatic debouncing, ensure `debounceTimeout` is set to a positive number (e.g., `300`). If `Enter`-only notification is intended, clearly communicate this behavior to users.

affects: >=2.4.0

gotchaWhen the `minLength` prop is specified, if the input's value becomes shorter than this minimum (e.g., by deleting characters), an `onChange` event will be triggered with an empty string (`''`) as its value.

fix

Implement checks in your `onChange` handler to gracefully manage empty string values, especially when dealing with validation or search queries that expect a minimum length.

affects: >=2.4.0

gotchaThe `forceNotifyByEnter` prop defaults to `true`. This can lead to unexpected behavior for `<textarea>` elements, where users might expect to insert new lines with `Enter` without triggering an immediate `onChange` notification.

fix

When using `DebounceInput` with `element="textarea"`, consider explicitly setting `forceNotifyByEnter={false}` if you want `Enter` to behave as a standard newline character without forcing an `onChange` notification.

affects: >=2.4.0

breakingPrior to version 3.0.1, using `onBlur` or `onKeyPress` props could cause issues where notifications were not correctly forced or handled transparently.

fix

Upgrade to `react-debounce-input@3.0.1` or a newer version to ensure `onBlur` and `onKeyPress` props integrate seamlessly without unintended side effects on `onChange` notification.

affects: <3.0.1

Errors

Common errors & fixes

Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components)...

Attempting to use `DebounceInput` without a correct named import or via an incorrect default import.

fix

Ensure you are using `import { DebounceInput } from 'react-debounce-input';` to correctly import the named component.

npm ERR! ERESOLVE unable to resolve dependency tree ... peer react@"^15.3.0 || 16 || 17 || 18" from react-debounce-input@3.3.0

Your project's `react` version does not satisfy the `react-debounce-input` peer dependency requirements.

fix

Upgrade your `react` and `react-dom` packages to a version compatible with `^15.3.0 || 16 || 17 || 18`. For example, `npm install react@18 react-dom@18`.

TypeScript Error: Property 'value' does not exist on type 'EventTarget' or 'ChangeEvent<HTMLInputElement>'

Incorrectly typing the `event` parameter in the `onChange` handler, especially if the `element` prop is used with a custom component.

fix

Ensure the `event` parameter in your `onChange` handler is correctly typed, for example: `(event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => ...`.

Upgrade

Version history

3.3.0latest on npm

Audit

Dependencies

reactrequiredRequired as a peer dependency for the React component.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/nkbt/react-debounce-input ↗

packagehttps://www.npmjs.com/package/react-debounce-input ↗