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
| Option | Type | Description | Default |
|---|---|---|---|
delayMs | number | Wait after the last keystroke before onCommit runs. 0 calls onCommit on each keystroke. | 300 |
applyTimeoutMs | number | Wait after the last commit for value to reach a committed text. Then the input shows value again. Infinity keeps the typed text. | 1000 |
Result
| Member | Type | Meaning |
|---|---|---|
inputProps | DebouncedInputProps | The props to spread: value, onChange, onBlur, onKeyDown, onCompositionStart, and onCompositionEnd. |
getInputProps | (own?) => DebouncedInputProps | inputProps 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. |
inputValue | string | The text in the input. It equals inputProps.value. |
flush | () => void | Calls onCommit with a pending value at once. |
cancel | () => void | Drops a pending value and shows value again. |
When onCommit runs
- Blur calls
onCommitwith 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
valueagain. It does not callonCommit. - 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
onCommitwith the text so far. - The call goes to the
onCommitof the most recent render.
What the input shows
- While text is pending, the input keeps the text. When nothing is pending, a change of
valuefrom outside shows in the input. - A committed text is a text that
onCommitreceived. AfteronCommitruns, the input keeps the typed text until the parent applies the committed texts. Whenvaluechanges to a text thatonCommitdid not receive, the input showsvalue. - 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
valuereaches no committed text withinapplyTimeoutMs, the input showsvalue. - 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.
Related
- useDebounce: the hook, and the
inputDebounceMswait of the grid inputs. - isComposingKey: the key test that the hook uses.
- Quick search: a grid input that uses the hook.