useTypeahead
Adds APG type-to-focus search to a collection: printable keystrokes are buffered (resetting after a pause), and the first item whose label starts with the buffer is reported through onMatch. Pressing the same letter repeatedly cycles through the matches rather than filtering deeper. It moves nothing itself; pair it with the collection's own focus management, most often useListFocus or useGridFocus.
Signature
useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn| Name | Type and behavior |
|---|---|
options | UseTypeaheadOptions · requiredConfiguration object. |
options.getItemLabels | () => ReadonlyArray<string | null | undefined> · requiredReturns the item labels in DOM order. A null or empty entry marks a non-matchable slot and keeps indices aligned with the caller's items. |
options.onMatch | (index: number) => void · requiredCalled with the index of the matched item so the caller can focus or select it; typically useListFocus's focusItem. |
options.getCurrentIndex | () => number · optional · default () => -1The index to search from, usually the focused item, so repeated presses of one letter cycle through matches. A negative value means nothing is current. |
options.resetMs | number · optional · default 750Milliseconds of inactivity after which the typed buffer resets. |
options.isDisabled | (index: number) => booleanWhether an index should be skipped, e.g. disabled items. |
| Name | Type and behavior |
|---|---|
onKeyDown | (e: React.KeyboardEvent | KeyboardEvent) => booleanKeydown handler. Returns true when it consumed a printable character, so the caller can stop its own key handling. |
reset | () => voidClears the pending buffer, e.g. when the collection closes. |
Usage
Adds APG type-to-focus search to a collection: printable keystrokes are buffered (resetting after a pause), and the first item whose label starts with the buffer is reported through onMatch. Pressing the same letter repeatedly cycles through the matches rather than filtering deeper. It moves nothing itself; pair it with the collection's own focus management, most often useListFocus or useGridFocus.
- Wire onMatch to the focus manager you already have (useListFocus.focusItem) instead of moving focus yourself.
- Let it see the key event first and fall through to arrow-key navigation only when it returns false.
- Pass getCurrentIndex so repeated presses of one letter walk through matches instead of sticking on the first.
- Use it on a text input; the field already receives the characters, and typeahead would fight the value.