react-relaxed 🐌

React Hooks for debouncing and throttling inputs or any other changing value

---

Installation

NPM

npm install react-relaxed

Yarn

yarn add react-relaxed

Demo

Try with Codesandbox

Usage

Debounce

Delays updating the returned debouncedValue variable until a given number of miliseconds have elapsed since the last time the value argument was changed.

import { useState } from "react";
import { useDebounce } from "react-relaxed";

const App = () => {
  const [value, setValue] = useState("initial value");
  const [debouncedValue] = useDebounce(value, 500);

  return (
    <div>
      <input value={value} onChange={(event) => setValue(event.target.value)} />
      <p>{value}</p>
      <p>{debouncedValue}</p>
    </div>
  );
};

With useDebounceState you do not need a seperate useState hook to keep track of the state. Apart form that, it's the same as useDebounce.

import { useDebounceState } from "react-relaxed";

const App = () => {
  const [value, setValue, debouncedValue] = useDebounceState("initial value", 500);

  return (
    <div>
      <input value={value} onChange={(event) => setValue(event.target.value)} />
      <p>{value}</p>
      <p>{debouncedValue}</p>
    </div>
  );
};

Throttle

The returned throttledValue gets updated at must once every given number of miliseconds, assuming the value argument changes more often than that.

import { useState } from "react";
import { useThrottle } from "react-relaxed";

const App = () => {
  const [value, setValue] = useState("initial value");
  const [throttledValue] = useThrottle(value, 500);

  return (
    <div>
      <input value={value} onChange={(event) => setValue(event.target.value)} />
      <p>{value}</p>
      <p>{throttledValue}</p>
    </div>
  );
};

With useThrottleState you do not need a seperate useState hook to keep track of the state. Apart form that, it's the same as useThrottle.

import { useThrottleState } from "react-relaxed";

const App = () => {
  const [value, setValue, throttledValue] = useThrottleState("initial value", 500);

  return (
    <div>
      <input value={value} onChange={(event) => setValue(event.target.value)} />
      <p>{value}</p>
      <p>{throttledValue}</p>
    </div>
  );
};

API

useDebounce

const [debouncedValue] = useDebounce(value, delay, {
  onChange,
  leading,
  trailing,
  maxWait,
});

Returns

• debouncedValue: T = any
  • The debounced value

Arguments

• value: T = any
  • Input value that gets debounced
• delay: number
  • Number of miliseconds that must have elapsed since the last time value was changed before debouncedValue gets updated
• leading: boolean = false
  • Update debouncedValue at the leading edge
  • Update takes place before each delay
• trailing: boolean = true
  • Update debouncedValue at the leading edge
  • Update takes place after each delay
• onChange: fn(value) => void
  • Input value that gets debounced
• maxWait: number
  • Number of miliseconds after which debouncedValue gets updated, even if there is continous input

useDebounceState

const [value, setValue, debouncedValue] = useDebounceState(initialValue, delay, {
  onChange,
  leading,
  trailing,
  maxWait,
});

Returns

• value: T = any
  • Value state
• setValue: React.SetStateAction
  • Sets / updates value state
• debouncedValue: T = any
  • The debounced value

Arguments

• initialValue: T = any
  • Initial value for state
• delay: number
  • Number of miliseconds that must have elapsed since the last time value was changed before debouncedValue gets updated
• leading: boolean = false
  • Update debouncedValue at the leading edge
  • Update takes place before each delay
• trailing: boolean = true
  • Update debouncedValue at the leading edge
  • Update takes place after each delay
• onChange: fn(value) => void
  • Input value that gets debounced
• maxWait: number
  • Number of miliseconds after which debouncedValue gets updated, even if there is continous input

useThrottle

const [throttledValue] = useThrottle(value, delay, {
  onChange,
  leading,
  trailing,
});

Returns

• throttled: T = any
  • The throttled value

Arguments

• value: T = any
  • Input value that gets throttled
• delay: number
  • Number of miliseconds between every update of throttledValue, provided value argument changes more often than that
• leading: boolean = false
  • Update debouncedValue at the leading edge
  • Update takes place before each delay
• trailing: boolean = true
  • Update debouncedValue at the leading edge
  • Update takes place after each delay
• onChange: fn(value) => void
  • Input value that gets debounced

useThrottleState

const [value, setValue, throttledValue] = useThrottleState(initialValue, delay, {
  onChange,
  leading,
  trailing,
});

Returns

• value: T = any
  • Value state
• setValue: React.SetStateAction
  • Sets / updates value state
• throttled: T = any
  • The throttled value

Arguments

• initialValue: T = any
  • Initial value for state
• delay: number
  • Number of miliseconds that must have elapsed since the last time value was changed before throttledValue gets updated
• leading: boolean = false
  • Update throttledValue at the leading edge
  • Update takes place before each delay
• trailing: boolean = true
  • Update debouncedValue at the leading edge
  • Update takes place after each delay
• onChange: fn(value) => void
  • Input value that gets debounced

Other solutions

use-debounce

Credits

This package used create-react-hook CLI for setting up the build proccess.

License

react-relaxed is available under the MIT license. See the LICENSE file for more info.