React Debounced Input Component

Common errors

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

  cause 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

  cause 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>'

  cause 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>) => ...`.

Warnings

• breaking React 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`.
• gotcha Setting `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.
• gotcha When 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.
• gotcha The `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.
• breaking Prior 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.

Install

• npm install react-debounce-input npm
• yarn add react-debounce-input yarn
• pnpm add react-debounce-input pnpm

Imports

• DebounceInput
  wrong:

  import DebounceInput from 'react-debounce-input';

  correct:

  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.

Quickstart

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);