gridcn2.0.0
Types and hooks

useDebouncedInput

Drive a text input that shows each keystroke at once, calls `onCommit` when the typing pauses, and keeps the last keystrokes on blur, Enter, and unmount.

useDebouncedInput drives a text input. The input shows each keystroke at once. onCommit runs once with the text of the input, after the typing pauses. The toolbar search, the filter value inputs, find and replace, and the lookup editor use the hook.

pnpm dlx shadcn@latest add @gridcn/use-debounce

The hook ships in the use-debounce item, next to useDebounce.

useDebouncedInput

function useDebouncedInput(
  value: string,
  onCommit: (next: string) => void,
  options?: UseDebouncedInputOptions,
): UseDebouncedInputResult;

value is the text that the parent holds. Spread inputProps on an input or a textarea:

import { useState } from "react";
import { useDebouncedInput } from "@/components/gridcn/use-debounce";

export function NameInput() {
  const [name, setName] = useState("");
  const input = useDebouncedInput(name, setName);
  return <input {...input.inputProps} />;
}

name changes 300 ms after the last keystroke. The input shows the typed text meanwhile.

To run your own handler too, spread getInputProps({ onKeyDown }) in place of inputProps. Your handler runs first, then the one of the hook. If your handler calls event.preventDefault(), the hook handler does not run for that event. A handler that you place after a plain inputProps spread replaces the one of the hook.

Options

OptionTypeDescriptionDefault
delayMsnumberWait after the last keystroke before onCommit runs. 0 calls onCommit on each keystroke.300
applyTimeoutMsnumberWait after the last commit for value to reach a committed text. Then the input shows value again. Infinity keeps the typed text.1000

Result

MemberTypeMeaning
inputPropsDebouncedInputPropsThe props to spread: value, onChange, onBlur, onKeyDown, onCompositionStart, and onCompositionEnd.
getInputProps(own?) => DebouncedInputPropsinputProps with the handlers in own chained. Each handler in own runs first, then the one of the hook, unless it calls event.preventDefault(). Other props in own, such as className, pass through.
inputValuestringThe text in the input. It equals inputProps.value.
flush() => voidCalls onCommit with a pending value at once.
cancel() => voidDrops a pending value and shows value again.

When onCommit runs

  • Blur calls onCommit with a pending value.
  • Enter does the same.
  • Unmount does the same, so closing a popover during the wait keeps the last keystrokes.
  • Escape drops a pending value and shows value again. It does not call onCommit.
  • During an IME composition (text that an input method editor builds, see isComposingKey), the wait does not run, and Enter and Escape do nothing. When the composition ends, the hook schedules the call. Blur and unmount still call onCommit with the text so far.
  • The call goes to the onCommit of the most recent render.

What the input shows

  • While text is pending, the input keeps the text. When nothing is pending, a change of value from outside shows in the input.
  • A committed text is a text that onCommit received. After onCommit runs, the input keeps the typed text until the parent applies the committed texts. When value changes to a text that onCommit did not receive, the input shows value.
  • If the user types a committed text again, the echoes in between can show for a moment. The input ends on the typed text.
  • If value reaches no committed text within applyTimeoutMs, the input shows value.
  • The hook remembers the last 64 committed texts that the parent has not applied. A late echo of one of them does not replace newer typing. The echo of an older text counts as a change from outside.

On this page