diff --git a/docs/hooks/use-debounce.md b/docs/hooks/use-debounce.md new file mode 100644 index 0000000..b923578 --- /dev/null +++ b/docs/hooks/use-debounce.md @@ -0,0 +1,46 @@ +# useDebounce + +Debounce a value. + +```ts +const debouncedValue = useDebounce(value, { timeout: 1000 }); +``` + +## Parameters + +### value + +- Type: `T` + +The value to be debounced. + +### options + +- Type: `UseDebounceOptions` +- Default: `{}` + +The options to configure the hook. + +## Options + +### timeout + +- Type: `number` +- Default: 500 + +The timeout in milliseconds between the last action of change and the actual time of that change being applied. + +Changes of this value will clear the current timer (with the old `timeout` value) and start a new one (with the new `timeout` value). + +### onMount + +- Type: `boolean` +- Default: `false` + +Whether to immediately start debouncing after the component is mounted. + +## Returns + +- Type: `T` + +The debounced value. diff --git a/src/use-debounce.ts b/src/use-debounce.ts index fdfbb1a..fe51018 100644 --- a/src/use-debounce.ts +++ b/src/use-debounce.ts @@ -1,13 +1,36 @@ import { useState } from "react"; import { useDebounceEffect } from "./use-debounce-effect"; +/** + * The options to configure the `useDebounce` hook. + */ export type UseDebounceOptions = { + /** + * The timeout in milliseconds between the last action of change and the + * actual time of that change being applied. + * + * Changes of this value will clear the current timer (with the old `timeout` + * value) and start a new one (with the new `timeout` value). + * + * @default 500 + */ timeout?: number; + + /** + * Whether to immediately start debouncing after the component is mounted. + * + * @default false + */ onMount?: boolean; }; /** * Debounce a value. + * + * @param value The value to be debounced. + * @param options The options to configure the hook. + * + * @returns The debounced value. */ export function useDebounce(value: T, options: UseDebounceOptions = {}) { const [debouncedValue, setDebouncedValue] = useState(value);