Skip to content

bill-kerr/react-dynamic-debounce

Repository files navigation

react-dynamic-debounce

A debounce hook that dynamically adjusts to input speed.

Quick Start

npm i react-dynamic-debounce
import { useDynamicDebounce } from 'react-dynamic-debounce';

function BasicExample() {
	const [debouncedValue, setDebouncedValue, { delay }] = useDynamicDebounce('Hello World', {
		defaultDelay: 500,
		delayFunction: (averageGap) => Math.floor(averageGap + 275),
	});

	return (
		<>
			<input type="text" onChange={(e) => setDebouncedValue(e.target.value)} defaultValue={debouncedValue} />
			<p>The current delay (ms): {delay}</p>
			<p>My debounced value: {debouncedValue}</p>
		</>
	);
}

API

useDynamicDebounce(initialState, options?)

A debounce hook that can adjust its debounce delay based on input speed. Provide a delayFunction to customize this behavior. Use this hook as you would useState.

export function useDynamicDebounce<S>(
	initialState: S | (() => S),
	config?: UseDynamicDebounceConfig,
): [S, React.Dispatch<React.SetStateAction<S>>, UseDynamicDebounceBag];
Parameter Type Description
initialState (S | () => S) The initial state value.
config UseDynamicDebounceConfig Config object, allowing customization of behavior.

useDynamicDebounceCallback(callback, options?)

A hook that returns a debounced callback with the same behavior and customization options as useDynamicDebounce.

export function useDynamicDebounceCallback<T extends unknown[]>(
	callback: (...args: T) => void,
	config?: UseDynamicDebounceConfig,
): [(...args: T) => void, UseDynamicDebounceBag]

UseDynamicDebounceConfig

Pass any number of arguments from this object as the second argument to either useDynamicDebounce or useDynamicDebounceCallback to customize its behavior.

Option Type Default Value Description
defaultDelay number 275 The amount of time in milliseconds that values will be initially debounced. The debounce time will also reset to this once it is triggered.
minDelay number 0 The minimum debounce time in milliseconds.
maxDelay number 825 The maximum debounce time in milliseconds.
delayFunction (averageGap: number) => number (averageGap) => Math.floor(averageGap) A function that receives the average time in milliseconds between input events and returns what the corresponding debounce time should be. This will only trigger once minSamples has been reached.
minSamples number 6 The minimum number of input events that will happen before the delay function is called. Cannot be below 2.
maxSamples number 10 The maximum number of input events that will be used to calculate the averageGap that gets passed to the delay function.
// Debounce hook with logarithmic delay function

const [value, setValue, { isDebouncing }] = useDynamicDebounce('Hello World!', {
	defaultDelay: 700,
	minDelay: 300,
	maxDelay: Infinity,
	delayFunction: (gap) => -470 + 199 * Math.log(gap),
	minSamples: 4,
	maxSamples: 8,
});

UseDynamicDebounceBag

UseDynamicDebounceBag are the values returned as the third return value from useDynamicDebounce or the second from useDynamicDebounceCallback.

Value Type Description
delay number The current debounce delay in milliseconds
isDebouncing boolean A boolean indicating whether or not a debounce delay is active

About

A debounce hook that dynamically adjusts to input speed

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published