AutoComplete is an input component that provides real-time suggestions while being typed
import { AutoComplete } from 'primereact/autocomplete';
AutoComplete is used as a controlled component with value and onChange properties. In addition, suggestions and a completeMethod are required to query the results.
<AutoComplete value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} />
Enabling dropdown property displays a button next to the input field where click behavior of the button is defined using dropdownMode property that takes blank or current as possible values. blank is the default mode to send a query with an empty string whereas current setting sends a query with the current value of the input.
<AutoComplete value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} dropdown />
AutoComplete can work with objects using the field property that defines the label to display as a suggestion. The value passed to the model would still be the object instance of a suggestion. Here is an example with a Country object that has name and code fields such as {name: "United States", code:"USA"}.
<AutoComplete field="name" value={selectedCountry} suggestions={filteredCountries} completeMethod={search} onChange={(e) => setSelectedCountry(e.value)} />
Custom content can be displayed as an option using itemTemplate property that references a function with a suggestion option as a parameter and returns an element. Similarly selectedItemTemplate property is available to customize the chips in multiple mode using the same approach. Note that selectedItemTemplate is only available in multiple mode at the moment.
<AutoComplete field="name" value={selectedCountry} suggestions={filteredCountries}
completeMethod={search} onChange={(e) => setSelectedCountry(e.value)} itemTemplate={itemTemplate} panelFooterTemplate={panelFooterTemplate} />
Option groups are specified with the optionGroupLabel and optionGroupChildren properties.
<AutoComplete value={selectedCity} onChange={(e) => setSelectedCity(e.value)} suggestions={filteredCities} completeMethod={search}
field="label" optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupedItemTemplate} placeholder="Hint: type 'a'" />
ForceSelection mode validates the manual input to check whether it also exists in the suggestions list, if not the input value is cleared to make sure the value passed to the model is always one of the suggestions. Simply enable forceSelection to enforce that input is always from the suggestion list.
<AutoComplete value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} forceSelection />
Virtual Scrolling is a performant way to render large lists. Configuration of the scroll behavior is defined with virtualScrollerOptionsthat requires itemSize as the mandatory value to set the height of an item. Visit VirtualScroller documentation for more information about the configuration API.
<AutoComplete value={selectedItem} suggestions={filteredItems} completeMethod={searchItems}
virtualScrollerOptions={{ itemSize: 38 }} field="label" dropdown onChange={(e) => setSelectedItem(e.value)} />
Multiple mode is enabled using multiple property used to select more than one value from the autocomplete. In this case, value reference should be an array. The number of values selectable can be restricted using the selectionLimit property.
<AutoComplete field="name" multiple value={selectedCountries} suggestions={filteredCountries} completeMethod={search} onChange={(e) => setSelectedCountries(e.value)} />
A floating label appears on top of the input field when focused.
<span className="p-float-label">
<AutoComplete inputId="ac" value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} />
<label htmlFor="ac">Float Label</label>
</span>
Invalid state style is added using the p-invalid class to indicate a failed validation.
<AutoComplete value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} className="p-invalid" />
When disabled is present, the element cannot be edited and focused.
<AutoComplete disabled placeholder="Disabled" />
Compatibility with popular React form libraries.
Formik is a popular library for handling forms in React.
<form onSubmit={formik.handleSubmit} className="flex flex-column gap-2">
<div className="mb-2">Value</div>
<Toast ref={toast} />
<AutoComplete
id="item"
name="item"
value={formik.values.item}
suggestions={items}
completeMethod={search}
onChange={(e) => {
formik.setFieldValue('item', e.value);
}}
/>
{getFormErrorMessage('item')}
<Button type="submit" label="Submit" className="mt-2" />
</form>
React Hook Form is another popular React library to handle forms.
<form onSubmit={form.handleSubmit(onSubmit)} className="flex flex-column gap-2">
<Toast ref={toast} />
<Controller
name="value"
control={form.control}
rules={{ required: 'Value is required.' }}
render={({ field, fieldState }) => (
<>
<label htmlFor={field.name}>
Value
</label>
<AutoComplete inputId={field.name} value={field.value} onChange={field.onChange} inputRef={field.ref} suggestions={items} completeMethod={search} className={classNames({ 'p-invalid': fieldState.error })} />
{getFormErrorMessage(field.name)}
</>
)}
/>
<Button label="Submit" type="submit" icon="pi pi-check" />
</form>
Following is the list of structural style classes, for theming classes visit theming page.
| Name | Element |
|---|---|
| p-autocomplete | Container element |
| p-autocomplete-panel | Overlay panel of suggestions. |
| p-autocomplete-items | List container of suggestions. |
| p-autocomplete-item | List item of a suggestion. |
| p-autocomplete-token | Element of a selected item in multiple mode. |
| p-autocomplete-token-icon | Close icon element of a selected item in multiple mode. |
| p-autocomplete-token-label | Label of a selected item in multiple mode. |
Value to describe the component can either be provided via label tag combined with inputId prop or using aria-labelledby, aria-label props. The input element has combobox role in addition to aria-autocomplete, aria-haspopup and aria-expanded attributes. The relation between the input and the popup is created with aria-controls and aria-activedescendant attribute is used to instruct screen reader which option to read during keyboard navigation within the popup list.
In multiple mode, chip list uses listbox role with aria-orientation set to horizontal whereas each chip has the option role with aria-label set to the label of the chip.
The popup list has an id that refers to the aria-controls attribute of the input element and uses listbox as the role. Each list item has option role and an id to match the aria-activedescendant of the input element.
<label htmlFor="ac1">Username</label>
<AutoComplete inputId="ac1" />
<span id="ac2">Email</span>
<AutoComplete aria-labelledby="ac2" />
<AutoComplete aria-label="City" />
| Key | Function |
|---|---|
| tab | Moves focus to the input element when popup is not visible. If the popup is open and an item is highlighted then popup gets closed, item gets selected and focus moves to the next focusable element. |
| up arrow | Highlights the previous item if popup is visible. |
| down arrow | Highlights the next item if popup is visible. |
| enter | Selects the highlighted item and closes the popup if popup is visible. |
| home | Highlights the first item if popup is visible. |
| end | Highlights the last item if popup is visible. |
| escape | Hides the popup. |
| Key | Function |
|---|---|
| backspace | Deletes the previous chip if the input field is empty. |
| left arrow | Moves focus to the previous chip if available and input field is empty. |
| Key | Function |
|---|---|
| left arrow | Moves focus to the previous chip if available. |
| right arrow | Moves focus to the next chip, if there is none then input field receives the focus. |
| backspace | Deletes the chips and adds focus to the input field. |