h3/use's logo

h3/use

Command Palette

Search for a command to run...

useDebounceState

Debounce the state update.

useDebounceState
This component uses the useDebounceState hook to debounce the state update.
Immediate value:
Debounced value:
The debounced value updates 1s after you stop typing.

Installation

Props

PropTypeDefaultDescription
defaultValueTundefinedThe default value of the state.
delaynumber500The delay in milliseconds before the state is updated.
optionsobject{}The options for the hook.

Options

PropTypeDefaultDescription
leadingbooleanfalseWhether to update the state immediately on first call.

Key Features & Details

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].

Examples

Basic Usage

const [value, setValue] = useDebouncedState('', 300);
setValue('new value');

With Leading Option

const [value, setValue] = useDebouncedState(0, 500, { leading: true });

With Updater Function

const [count, setCount] = useDebouncedState(0, 400);
setCount((prev) => prev + 1);