use-debounce-state (use-debounce-state)

Debounce the call of a function.

v0.1.0

Usage

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

"use client";

import { useState } from "react";

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

import { useDebouncedState } from "@/components/hooks/use-debounce-state";

export function UseDebounceStateDemo() {
  const [immediateValue, setImmediateValue] = useState("");
  const [debouncedValue, setDebouncedValue] = useDebouncedState("", 1000);

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

  return (
    <Card className="max-w-md w-full relative">
      <CardHeader>
        <CardTitle>useDebounceState</CardTitle>
        <CardDescription>
          This component uses the <code>useDebounceState</code> hook to debounce
          the state update.
        </CardDescription>
      </CardHeader>
      <CardContent className="space-y-4">
        <Input
          type="text"
          value={immediateValue}
          onChange={handleChange}
          placeholder="Type something..."
        />
      </CardContent>
      <CardFooter className="flex-col items-start gap-1">
        <div className="flex flex-col gap-1">
          <span className="text-sm text-muted-foreground">
            Immediate value:
          </span>
          <span className="font-mono bg-muted rounded px-2 py-1">
            {immediateValue}
          </span>
        </div>
        <div className="flex flex-col gap-1">
          <span className="text-sm text-muted-foreground">
            Debounced value:
          </span>
          <span className="font-mono bg-muted rounded px-2 py-1">
            {debouncedValue}
          </span>
        </div>
        <span className="text-sm text-muted-foreground mt-2">
          The debounced value updates 1s after you stop typing.
        </span>
      </CardFooter>
    </Card>
  );
}

Install

npx wkkkis-hooks add use-debounce-state

Options

Name	Type	Default	Description
defaultValue	T	undefined	The default value of the state.
delay	number	500	The delay in milliseconds before the state is updated.
options	object	{}	The options for the hook.
leading	boolean	false	Whether to update the state immediately on first call.

Debounced State Update

State updates are debounced: only the last value set within the delay period will be applied.
The setter function accepts either a value or an updater function (like React's setState ).

Leading Option

If options.leading is true , the state is updated immediately on the first call, then debounced for subsequent calls until the delay passes.
If false (default), the state is only updated after the delay.

Cleanup

Any pending timeout is cleared when the component unmounts or when a new value is set, preventing memory leaks or unexpected updates.

Best Practices & Caveats

The hook is client-side only.
For best performance, avoid creating new setter functions on every render.
If the component unmounts before the delay, the state will not update.
The hook returns a tuple: [value, setDebouncedValue] .

Files in this hook

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