use-debounce-callback (use-debounce-callback)

Debounce the call of a function.

v0.1.0

Usage

import { use-debounce-callback } from "@/hooks"

"use client";

import React, { useCallback, useState } from "react";

import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { Input } from "@/components/ui/input";

import { useDebounceCallback } from "@/components/hooks/use-debounce-callback";

export function UseDebounceCallbackDemo() {
  const [inputValue, setInputValue] = useState("");
  const [debouncedValue, setDebouncedValue] = useState("");

  const updateDebouncedValue = useCallback((value: string) => {
    setDebouncedValue(value);
  }, []);

  const debouncedUpdate = useDebounceCallback(updateDebouncedValue, 500);

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const value = e.target.value;
    setInputValue(value);
    debouncedUpdate(value);
  };

  return (
    <Card className="max-w-md w-full relative">
      <CardHeader>
        <CardTitle>useDebounceCallback</CardTitle>
        <CardDescription>
          This component uses the <code>useDebounceCallback</code> hook to
          debounce the callback function to control the input value.
        </CardDescription>
      </CardHeader>
      <CardContent>
        <Input
          type="text"
          value={inputValue}
          onChange={handleChange}
          placeholder="Type something..."
          className="w-full"
        />
      </CardContent>
      <CardFooter className="flex-col items-start gap-2">
        <p className="text-sm text-muted-foreground">
          <strong>Immediate value:</strong> {inputValue}
        </p>
        <p className="text-sm text-muted-foreground">
          <strong>Debounced value:</strong> {debouncedValue}
        </p>
      </CardFooter>
    </Card>
  );
}

Install

npx wkkkis-hooks add use-debounce-callback

Options

Name	Type	Default	Description
delay	number	500	The delay in milliseconds before the function is executed.
callback	generic T	undefined	The function to be executed after the delay.

Returns — Properties

Name	Type	Default	Description
The	—	—	returned function accepts the same arguments as the original callback.
If	—	—	called repeatedly, only the last call within the delay period will trigger the callback.
The	—	—	debounced function is stable (does not change identity unless delay changes).

Callback & Delay Handling

The hook always uses the latest version of the callback, even if it changes between renders.
The delay can be changed dynamically; the new delay will be used for subsequent calls.

Returned Debounced Function

The returned function accepts the same arguments as the original callback.
If called repeatedly, only the last call within the delay period will trigger the callback.
The debounced function is stable (does not change identity unless delay changes).

Cleanup

Any pending timeout is cleared when the component unmounts, preventing memory leaks or unexpected calls.

Best Practices & Caveats

The hook is client-side only.
For best performance, memoize the callback if it depends on other values.
If you need to cancel a pending debounce manually, you must manage that outside the hook.
The hook does not guarantee the callback will run if the component unmounts before the delay.

Files in this hook

Source	Destination
files/use-debounce-callback.ts	src/hooks/use-debounce-callback.ts