react-debounce-input

What is react-debounce-input?

The react-debounce-input package provides a React component that debounces the input value change events. This is useful for scenarios where you want to limit the rate at which a function is executed, such as when making API calls based on user input.

What are react-debounce-input's main functionalities?

Basic Debounced Input

This example demonstrates a basic usage of the DebounceInput component. The input value is debounced with a timeout of 300 milliseconds, meaning the onChange event will only be triggered if the user stops typing for 300 milliseconds.

import React, { useState } from 'react';
import { DebounceInput } from 'react-debounce-input';

function App() {
  const [value, setValue] = useState('');

  return (
    <div>
      <DebounceInput
        minLength={2}
        debounceTimeout={300}
        onChange={(event) => setValue(event.target.value)}
      />
      <p>Value: {value}</p>
    </div>
  );
}

export default App;

Debounced Input with Min Length

This example shows how to use the DebounceInput component with a minimum length requirement. The onChange event will only be triggered if the input value has at least 5 characters and the user stops typing for 500 milliseconds.

import React, { useState } from 'react';
import { DebounceInput } from 'react-debounce-input';

function App() {
  const [value, setValue] = useState('');

  return (
    <div>
      <DebounceInput
        minLength={5}
        debounceTimeout={500}
        onChange={(event) => setValue(event.target.value)}
      />
      <p>Value: {value}</p>
    </div>
  );
}

export default App;

Debounced Input with Element

This example demonstrates how to use the DebounceInput component with a different HTML element, such as a textarea. The input value is debounced with a timeout of 300 milliseconds.

import React, { useState } from 'react';
import { DebounceInput } from 'react-debounce-input';

function App() {
  const [value, setValue] = useState('');

  return (
    <div>
      <DebounceInput
        element="textarea"
        minLength={2}
        debounceTimeout={300}
        onChange={(event) => setValue(event.target.value)}
      />
      <p>Value: {value}</p>
    </div>
  );
}

export default App;

Other packages similar to react-debounce-input

lodash.debounce

The lodash.debounce package provides a function to debounce any function, not just input events. It is more versatile as it can be used in various scenarios beyond React components. However, it requires more manual setup compared to react-debounce-input.

react-throttle

The react-throttle package provides components for throttling and debouncing events in React. It offers similar functionality to react-debounce-input but also includes throttling capabilities, which can be useful for different use cases.

use-debounce

The use-debounce package provides a React hook for debouncing values and functions. It offers a more modern approach using hooks, which can be more convenient and flexible compared to the component-based approach of react-debounce-input.

README

react-debounce-input

React component that renders an Input, Textarea or other element with debounced onChange. Can be used as drop-in replacement for <input type="text" /> or <textarea />

Live design system demo

https://www.jinno.io/app/19

Simple web demo

http://nkbt.github.io/react-debounce-input

Codepen demo

http://codepen.io/nkbt/pen/VvmzLQ

Installation

NPM

npm install --save react-debounce-input

yarn

yarn add react-debounce-input 

1998 Script Tag:

<script src="https://unpkg.com/react@16.0.0/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-debounce-input/build/react-debounce-input.js"></script>
(Module exposed as `DebounceInput`)

Usage

import React from 'react';
import ReactDOM from 'react-dom';
import {DebounceInput} from 'react-debounce-input';

class App extends React.Component {
  state = {
    value: ''
  };

  render() {
    return (
      <div>
        <DebounceInput
          minLength={2}
          debounceTimeout={300}
          onChange={event => this.setState({value: event.target.value})} />

        <p>Value: {this.state.value}</p>
      </div>
    );
  }
}

const appRoot = document.createElement('div');
document.body.appendChild(appRoot);
ReactDOM.render(<App />, appRoot);

Options

element : PropTypes.string or React.PropTypes.func (default: "input")

You can specify element="textarea". For Example:

<DebounceInput element="textarea" />

Will result in

<textarea />

Note: when rendering a <textarea /> you may wish to set forceNotifyByEnter = {false} so the user can make new lines without forcing notification of the current value.

This package has only been tested with <input /> and <textarea /> but should work with any element which has value and onChange props.

You can also use a custom react component as the element. For Example:

<DebounceInput element={CustomReactComponent} />

Will result in

<CustomReactComponent />

onChange: PropTypes.func.isRequired

Function called when value is changed (debounced) with original event passed through

value: PropTypes.string

Value of the Input box. Can be omitted, so component works as usual non-controlled input.

minLength: PropTypes.number (default: 0)

Minimal length of text to start notify, if value becomes shorter then minLength (after removing some characters), there will be a notification with empty value ''.

debounceTimeout: PropTypes.number (default: 100)

Notification debounce timeout in ms. If set to -1, disables automatic notification completely. Notification will only happen by pressing Enter then.

forceNotifyByEnter: PropTypes.bool (default: true)

Notification of current value will be sent immediately by hitting Enter key. Enabled by-default. Notification value follows the same rule as with debounced notification, so if Length is less, then minLength - empty value '' will be sent back.

NOTE if onKeyDown callback prop was present, it will be still invoked transparently.

forceNotifyOnBlur: PropTypes.bool (default: true)

Same as forceNotifyByEnter, but notification will be sent when focus leaves the input field.

inputRef: PropTypes.func (default: undefined)

Will pass ref={inputRef} to generated input element. We needed to rename ref to inputRef since ref is a special prop in React and cannot be passed to children.

See ./example/Ref.js for usage example.

Arbitrary props will be transferred to rendered <input>

<DebounceInput
  type="number"
  onChange={event => this.setState({value: event.target.value})}
  placeholder="Name"
  className="user-name" />

Will result in

<input
  type="number"
  placeholder="Name"
  className="user-name" />

Typescript

This library has typescript typings, import them the same way as in javascript:

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

Also there are helper types DebounceTextArea and Debounced to provide strict interfaces for wrapping components different from standard <input />. Check usage examples in example/typescript-example.tsx.

NOTE library author is not using Typescript, so if you are using typings and found an issue, please submit a PR with fix. Thanks @iyegoroff for the initial TS support!

Development and testing

Currently is being developed and tested with the latest stable Node on OSX.

To run example covering all DebounceInput features, use yarn start, which will compile example/Example.js

git clone [e-mail]:nkbt/react-debounce-input.git
cd react-debounce-input
yarn install
yarn start

# then
open http://localhost:8080

Tests

# to run ESLint check
yarn lint

# to run tests
yarn test

License

MIT