What it does
useDebouncedCallback(callback, delayMs) schedules trailing-edge actions. Each call replaces the arguments and restarts the timer. It complements useDebouncedValue: use the value hook for derived state and this hook for delayed actions such as search or autosave.
API notes
Returns { debouncedCallback, cancel, flush, isPending }. The three functions keep their identity across renders. flush() invokes pending work immediately and returns the callback result (including a Promise), or undefined when idle. cancel() discards pending work. isPending is reactive timer state; it becomes false when the callback starts, even if an async request is still running. The callback uses the latest committed closure and last scheduled arguments. A finite delay from 0 through 2,147,483,647 ms is required; zero is still asynchronous. A changed delay applies to future calls and preserves an existing deadline. Unmount discards work without flushing. This hook supports trailing calls only; it has no leading-call or max-wait option.
Common use cases
Schedule draft saves or delayed search actions after typing pauses. Flush on an explicit Save action and cancel when abandoning a draft. Handle async results and failures inside the callback; cancellation does not stop requests that have already begun.
Accessibility
Keep text input updates immediate and debounce the action. Label controls and announce meaningful save status with a polite live region. Do not debounce focus movement or essential keyboard feedback.
Next.js integration notes
Import from @zentauri-ui/zentauri-components/hooks/useDebouncedCallback in a client component. Invoke the controls from events or effects, never during render. Extract plain input values before scheduling rather than retaining event objects. No timers are started during server rendering. The hook does not persist pending work across navigation; use a deliberate Save action when data must be committed before leaving.
FAQ
Can I import this hook from a server component?
No. These hooks rely on browser APIs or React client lifecycle. Import them from a file marked with the "use client" directive or from a client child component.
Does the preview site bundle the same code as npm?
The component library app depends on the workspace package. Published builds resolve the same export paths under @zentauri-ui/zentauri-components.
Where should I validate accessibility for hook-driven UI?
Hooks do not replace semantics. Test focus order, labels, and keyboard flows in your real layout with assistive technologies you support.