tiny-use-debounce
v1.0.4
Published
React hooks for debouncing and throttling.
Downloads
273
Maintainers
Readme
Tiny Use Debounce
React hooks for debouncing and throttling.
Features
- Tiny Size
- Highly customizable
- Fully tested
- TypeScript support out of the box
Installation
# npm
npm i tiny-use-debounce
# yarn
yarn add tiny-use-debounce
Usage
import { useDebounce, useThrottle } from "tiny-use-debounce";
import { debounce, throttle } from "lodash-es";
const App = () => {
const debouncedMouseMove = useDebounce(() => console.log("mouse move"), 300);
const throttledScroll = useDebounce(() => console.log("scroll"), 300);
return (
<div onMouseMove={debouncedMouseMove} onScroll={throttledScroll}>
{/* ... */}
</div>
);
};
Customizing
This library uses its own implementations of debounce
and throttle
functions. But in some cases, you may want to change it (not enough options, smaller bundle size, etc.). For this purpose, you could use createDebounceHook
:
import { createDebounceHook } from "tiny-use-debounce";
import { debounce, throttle } from "lodash";
const useDebounce = createDebounceHook(debounce);
const useThrottle = createDebounceHook(throttle);
const options = {
leading: true,
};
const App = () => {
const debouncedFn = useDebounce(() => console.log("here"), 100, options);
const throttledFn = useThrottle(() => console.log("here"), 100, options);
// ...
};
Memoization
By default, functions returned from hooks will always be memoized.
const debouncedFn = useDebounce(() => {
/* ... */
}, 100);
useEffect(() => {
/* ... */
}, [
//could be safely used as a dependency since reference will never change
debounceFn,
]);
But if you create your own hook with createDebounceHook
, you need to be a little more cautious. The first argument (the callback) will not make any effect on memoization. But other arguments will be compared referentially. So if your debounce
implementation uses objects as options they need to be declared outside of the component or memoized. Take a look at the example below:
import { createDebounceHook } from "tiny-use-debounce";
import { debounce, throttle } from "lodash";
const useDebounce = createDebounceHook(debounce);
const stableOptions = { leading: true };
const App = () => {
const options = { leading: true };
// this function will be recreated on each rerender
// because options object has new reference
const debounceFn1 = useDebounce(
() => {
/* ... */
},
100,
options
);
// this function will always have the same reference
// because all additional arguments have the same
// reference between renders
const debounceFn2 = useDebounce(
() => {
/* ... */
},
100,
stableOptions
);
const [leading, setLeading] = useState(true);
const memoOptions = useMemo(() => ({ leading }), [leading]);
// this function will only update when `leading`
// changes, other updates will not break memoization
const debounceFn3 = useDebounce(
() => {
/* ... */
},
100,
memoOptions
);
};
API
useDebounce
Creates debounced function.
Usage:
useDebounce(cb, wait)
Type:
function useDebounce<
Callback extends AnyFunction
>(
cb: Callback,
wait: number
) => ((...args: Parameters<Callback>) => void) & {
cancel: () => void;
};
useThrottle
Creates throttled function.
Usage:
useThrottle(cb, wait)
Type:
function useDebounce<
Callback extends AnyFunction
>(
cb: Callback,
wait: number
) => ((...args: Parameters<Callback>) => void) & {
cancel: () => void;
};
createDebounceHook
Creates hook that uses proved function for debouncing.
Usage:
createDebounceHook(debounce)
Type:
function createDebounceHook<DebounceFn extends AnyFunction>(
debounce: DebounceFn
): <Callback extends AnyFunction>(
cb: Callback,
...rest: Tail<Parameters<DebounceFn>>
) => DebounceFunction<Callback, DebounceFn>;