AutocompleteInput

A single-select input with type-ahead over a list of choices.

Installation

pnpm dlx shadcn@latest add @chelone/autocomplete-input

Loading preview…

A single-select input with type-ahead over a list of choices.

Props

Prop	Type	Default	Description
alwaysOn	boolean	—	As a `<FilterForm>`/`<FilterButton>` filter: always shown, never in the add-filter menu. Read off the element by the filter layer, never by the input.
defaultValue	NoInfer<SourceValue<TRecord, TPath>>	—	Input-level default, ra precedence (seeds only into an untouched hole). Typed as the value at `source`; `unknown` without a record.
disabled	boolean	—	Native disabled state.
helperText	ReactNode	—	Helper text rendered below the input; a string is translated.
id	string	—	Explicit element id; a generated `useId` value is used otherwise.
isRequired	boolean	—	Forces the required marker; ORed with `required()` detection on `validate`.
label	ReactNode	—	The input label. A string is translated; a ReactNode renders as-is; `false` (or `""`) renders no label.
name	string	—	Legacy field-name alias (ra parity); the wiring uses `source`.
onBlur	(event: unknown) => void	—	Chained AFTER the blur is recorded.
onChange	(eventOrValue: unknown) => void	—	Chained AFTER the parsed value is written to the form.
parse	(value: unknown) => NoInfer<SourceTransformValue<TRecord, TPath>>	—	Write transform (input value → stored value). Must return the value at `source`; `unknown` without a record.
readOnly	boolean	—	Native read-only state.
resource	string	—	Override the ambient resource (used to resolve the default label key).
type	string	—	The DOM input `type` (text inputs default to `"text"`).
validate	Validator \| readonly Validator[]	—	ra-contract validators — composed, first error wins.
source	TPath	—	The field path RELATIVE to the ambient source scope.
className	string	—
clearOnBlur	boolean	—	When true, clear the filter text on input blur.
debounce	number	—
emptyText	string	—	Label of a "(none)" entry prepended when the field is not required.
emptyValue	string \| number	—	Underlying value used when clearing the selection. Defaults to "".
filterToQuery	(searchText: string) => FilterPayload	—
handleHomeEndKeys	boolean	—	When true, Home/End keys scroll the listbox to first/last item.
inputText	(choice: TChoice) => string	—	Custom display text for the selected value in the trigger.
isOptionEqualToValue	(option: ChoiceValueOf<TChoice>, value: ChoiceValueOf<TChoice>) => boolean	—	Custom equality check between a choice value and the current value.
limitChoicesToValue	boolean	—	When true, only show choices matching the current value.
matchSuggestion	(filter: string, choice: TChoice) => boolean	—	Custom filter function; replaces default substring match.
modal	boolean	—	Radix popover modality.
noOptionsText	React.ReactNode	—	Content to show when no choices match the filter.
openOnFocus	boolean	—	When true, open the dropdown on input focus.
placeholder	string	—
selectOnFocus	boolean	—	When true, select all text in the input on focus.
setFilter	(filter: string) => void	—	Called with the current filter text on every keystroke (no debounce).
shouldRenderSuggestions	(filter: string) => boolean	—	Gate controlling whether the dropdown opens at all.
suggestionLimit	number	—	Cap the number of dropdown items shown.