useAutoComplete

Hook that manages autocomplete state, search callbacks, and popup positioning for combobox inputs.

basic-demo

Usage#

import { useAutoComplete } from '@primereact/headless/autocomplete';
 
const autocomplete = useAutoComplete({ options: filteredItems, onComplete: search });
const { rootProps, inputProps, triggerProps, listProps, positionerProps, popupProps, arrowProps, state, listbox } = autocomplete;
 
return (
    <div {...rootProps}>
        <input {...inputProps} />
        <button {...triggerProps}></button>
        <div {...positionerProps}>
            <div {...popupProps}>
                <ul {...listProps}>...</ul>
            </div>
            <div {...arrowProps} />
        </div>
    </div>
);

useAutoComplete composes useListbox and usePopover internally, managing search callbacks, input value synchronization, and popup lifecycle — see Primitive for a component-based API.

Features#

rootProps, inputProps, triggerProps, listProps, positionerProps, popupProps, arrowProps, indicatorProps, and clearProps return spread-ready prop objects
Composes useListbox internally — the returned listbox instance provides option iteration, selection state, and useListboxOption support
onComplete callback fires with the current query for custom filtering logic
show(), hide(), toggle(), and focus() for imperative popup and input control
getSelectedOptionLabel() and hasValue() for reading the current selection
setRendered() controls whether the overlay has been rendered at least once, useful for lazy rendering strategies

Behavior#

Default Value#

Set defaultValue for uncontrolled selection.

const autocomplete = useAutoComplete({ options: items, onComplete: search, defaultValue: 'React' });

Default Input Value#

Set defaultInputValue to provide an initial input text in uncontrolled mode. This is independent of defaultValue — it controls only the text shown in the input field.

const autocomplete = useAutoComplete({ options: items, onComplete: search, defaultInputValue: 'Rea' });

Controlled#

Pass value and onValueChange for controlled selection state.

const [selected, setSelected] = React.useState(null);
 
const autocomplete = useAutoComplete({
    options: items,
    onComplete: search,
    value: selected,
    onValueChange: (e) => setSelected(e.value)
});

Controlled Input Value#

Use inputValue and onInputValueChange to control the text input independently from the selection. This is useful for custom filtering, clearing the input programmatically, or syncing the query with external state.

const [query, setQuery] = React.useState('');
 
const autocomplete = useAutoComplete({
    options: items,
    onComplete: search,
    inputValue: query,
    onInputValueChange: (e) => setQuery(e.query)
});

Option Fields#

Use optionLabel, optionValue, optionDisabled, and optionKey to map fields when options are objects.

const autocomplete = useAutoComplete({
    optionLabel: 'name',
    optionValue: 'code',
    optionDisabled: 'inactive',
    optionKey: 'code'
});

Grouped Options#

Set optionGroupLabel and optionGroupChildren to support grouped option structures.

const autocomplete = useAutoComplete({
    optionGroupLabel: 'label',
    optionGroupChildren: 'items'
});

Search Delay#

Set delay to debounce the onComplete callback in milliseconds.

const autocomplete = useAutoComplete({ delay: 300 });

Minimum Length#

Set minLength to require a minimum number of characters before triggering the search.

const autocomplete = useAutoComplete({ minLength: 2 });

Force Selection#

Enable forceSelection to clear the input on blur if the typed value does not match any option.

const autocomplete = useAutoComplete({ forceSelection: true });

Disabled#

Set disabled to prevent all interaction.

const autocomplete = useAutoComplete({ disabled: true });

Focus Behavior#

Use autoOptionFocus to automatically focus the first option when the popup opens, selectOnFocus to select while navigating, and focusOnHover to move focus with mouse hover.

const autocomplete = useAutoComplete({ autoOptionFocus: true, selectOnFocus: true });

Use open and onOpenChange for controlled popup state, or defaultOpen for uncontrolled initial state.

const [open, setOpen] = React.useState(false);
 
const autocomplete = useAutoComplete({
    open,
    onOpenChange: (e) => setOpen(e.value)
});

Set closeOnEscape to dismiss the overlay with the Escape key, autoFocus to move focus into the overlay when it opens, and trapped to keep focus within the overlay.

const autocomplete = useAutoComplete({ closeOnEscape: true, autoFocus: true, trapped: true });

Meta Key Selection#

Enable metaKeySelection to require holding the meta key (Cmd/Ctrl) to select or deselect an option.

const autocomplete = useAutoComplete({ metaKeySelection: true });

Locale#

Set locale to control the locale used for string comparison during force selection matching.

const autocomplete = useAutoComplete({ locale: 'tr-TR', forceSelection: true });

Form Integration#

Use name to set the input's name attribute for form submission, and tabIndex to control the tab order.

const autocomplete = useAutoComplete({ name: 'city', tabIndex: 0 });

Custom Styling with Data Attributes#

Every prop object includes data-scope="autocomplete" and a data-part that identifies the element. State-driven attributes appear or disappear automatically.

Part	State Attributes
`trigger`	`data-positioner-open`
`popup`	`data-open`
`indicator`	`data-open`, `data-closed`

Options rendered via useListboxOption use data-scope="listbox" with the following state attributes.

Part	State Attributes
`option`	`data-selected`, `data-unselected`, `data-focused`, `data-disabled`
`optionindicator`	`data-selected`, `data-unselected`

/* Input focus ring */
[data-scope='autocomplete'][data-part='input']:focus {
    outline: 2px solid var(--p-primary-color);
    outline-offset: -2px;
}
 
/* Open/close indicator rotation */
[data-scope='autocomplete'][data-part='indicator'][data-open] {
    transform: rotate(180deg);
}
 
/* Popup entrance */
[data-scope='autocomplete'][data-part='popup'][data-open] {
    border: 1px solid var(--p-content-border-color);
    border-radius: 6px;
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}
 
/* Option states */
[data-scope='listbox'][data-part='option'][data-focused] {
    background: var(--p-surface-100);
}
[data-scope='listbox'][data-part='option'][data-selected] {
    background: var(--p-primary-color);
    color: var(--p-primary-contrast-color);
}
[data-scope='listbox'][data-part='option'][data-disabled] {
    opacity: 0.5;
    pointer-events: none;
}

API#