lara-light-indigo

AutoComplete

AutoComplete is an input component that provides real-time suggestions when being typed.

Basic
Grouped
Dropdown, Templating and Force Selection
Virtual Scroll (100000 Items)
Multiple
Import via Module

import { AutoComplete } from 'primereact/autocomplete';
 
Import via CDN

<script src="https://unpkg.com/primereact/core/core.min.js"></script>
<script src="https://unpkg.com/primereact/autocomplete/autocomplete.min.js"></script>
 
Getting Started

AutoComplete is used as a controlled component with value and onChange properties. In addition, the component requires a list of suggestions and a completeMethod to query the results.


<AutoComplete value={selectedCountry} suggestions={filteredCountries} completeMethod={searchCountry} field="name" onChange={(e) => setSelectedCountry(e.value)} />
 

const countries = // datasource

const searchCountry = (event) => {
    let filteredCountries = //suggestions
    setFilteredCountries(filteredCountries);
}

render() {
    return (
        <AutoComplete value={selectedCountry} suggestions={filteredCountries} completeMethod={searchCountry} onChange={(e) => setSelectedCountry(e.value)} />
    );
}
 
Dropdown

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 dropdown value={selectedCountry} suggestions={filteredCountries} completeMethod={searchCountry} onChange={(e) => setSelectedCountry(e.value)} />
 
Multiple Mode

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.


<AutoComplete multiple value={selectedCountry} suggestions={filteredCountries} completeMethod={searchCountry} onChange={(e) => setSelectedCountry(e.value)} />
 
Objects

AutoComplete can also 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={searchCountry} onChange={(e) => setSelectedCountry(e.value)} />
 
Grouping

Options groups are specified with the optionGroupLabel and optionGroupChildren properties.


const groupedCities = [
    {
        label: 'Germany', code: 'DE',
        items: [
            { label: 'Berlin', value: 'Berlin' },
            { label: 'Frankfurt', value: 'Frankfurt' },
            { label: 'Hamburg', value: 'Hamburg' },
            { label: 'Munich', value: 'Munich' }
        ]
    },
    {
        label: 'USA', code: 'US',
        items: [
            { label: 'Chicago', value: 'Chicago' },
            { label: 'Los Angeles', value: 'Los Angeles' },
            { label: 'New York', value: 'New York' },
            { label: 'San Francisco', value: 'San Francisco' }
        ]
    },
    {
        label: 'Japan', code: 'JP',
        items: [
            { label: 'Kyoto', value: 'Kyoto' },
            { label: 'Osaka', value: 'Osaka' },
            { label: 'Tokyo', value: 'Tokyo' },
            { label: 'Yokohama', value: 'Yokohama' }
        ]
    }
];
 

<AutoComplete value={selectedCity} suggestions={filteredCities} completeMethod={searchCity} field="label" optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupedItemTemplate} onChange={(e) => setSelectedCity(e.value)}/>
 
Force Selection

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 forceSelection value={selectedCountry} suggestions={filteredCountries} completeMethod={searchCountry} onChange={(e) => setSelectedCountry(e.value)} />
 
Templating

Custom content can be displayed using itemTemplate property that references a function or JSXElement or string which gets the suggestion option and returns an element. Similarly selectedItemTemplate property is available to customize the chips in multiple mode using the same approach.


<AutoComplete value={selectedCountry} suggestions={filteredCountries} completeMethod={searchCountry} onChange={(e) => setSelectedCountry(e.value)} itemTemplate={itemTemplate} />
 

itemTemplate(item) {
    //return custom element
}
 
Properties
NameTypeDefaultDescription
idstringnullUnique identifier of the element.
valueanynullValue of the component.
namestringnullName of the input element.
typestringtextType of the input element.
suggestionsarraynullAn array of suggestions to display.
fieldanynullField of a suggested object to resolve and display.
optionGroupLabelstringnullProperty name or getter function to use as the label of an option group.
optionGroupChildrenstringnullProperty name or getter function that refers to the children options of option group.
forceSelectionbooleanfalseWhen present, autocomplete clears the manual input if it does not match of the suggestions to force only accepting values from the suggestions.
autoHighlightbooleanfalseWhen enabled, highlights the first item in the list by default.
scrollHeightstring200pxMaximum height of the suggestions panel.
dropdownbooleanfalseDisplays a button next to the input field when enabled.
dropdownModestringblankSpecifies the behavior dropdown button. Default "blank" mode sends an empty string and "current" mode sends the input value.
multiplebooleanfalseSpecifies if multiple values can be selected.
minLengthnumber1Minimum number of characters to initiate a search.
delaynumber300Delay between keystrokes to wait before sending a query.
stylestringnullInline style of the component.
classNamestringnullStyle class of the component.
inputIdstringnullIdentifier of the input element.
inputStylestringnullInline style of the input field.
inputClassNamestringnullInline style of the input field.
panelClassNamestringnullStyle class of the overlay panel element.
panelStylestringnullInline style of the overlay panel element.
placeholderstringnullHint text for the input field.
readOnlybooleanfalseWhen present, it specifies that the input cannot be typed.
disabledbooleanfalseWhen present, it specifies that the component should be disabled.
maxlengthnumbernullMaximum number of character allows in the input field.
sizenumbernullSize of the input field.
appendToDOM element | stringdocument.bodyDOM element instance where the overlay panel should be mounted. Valid values are any DOM Element and 'self'. The self value is used to render a component where it is located.
tabIndexnumbernullIndex of the element in tabbing order.
autoFocusbooleanfalseWhen present, it specifies that the component should automatically get focus on load.
tooltipanynullContent of the tooltip.
tooltipOptionsobjectnullConfiguration of the tooltip, refer to the tooltip documentation for more information.
ariaLabelledBystringnullEstablishes relationships between the component and label(s) where its value should be one or more element IDs.
itemTemplateanynullTemplate of a list item.
selectedItemTemplateanynullTemplate of a selected item.
optionGroupTemplateanynullTemplate of an option group item.
transitionOptionsobjectnullThe properties of CSSTransition can be customized, except for "nodeRef" and "in" properties.
dropdownIconanypi pi-chevron-downIcon class of the dropdown icon.
removeIconanypi pi-times-circleIcon of the remove chip element in multiple mode.
virtualScrollerOptionsobjectnullWhether to use the virtualScroller feature. The properties of VirtualScroller component can be used like an object in it.
Events
NameParametersDescription
completeMethodevent.originalEvent: browser event
event.query: Value to search with
Callback to invoke to search for suggestions.
onChangeevent.originalEvent: Browser event
event.value: Value of the component
Callback to invoke when autocomplete value changes.
onFocusevent: Browser eventCallback to invoke when autocomplete gets focus.
onBlurevent: Browser eventCallback to invoke when autocomplete loses focus.
onSelectevent.originalEvent: Browser event
event.value: Value of the component
Callback to invoke when a suggestion is selected.
onUnselectevent.originalEvent: Browser event
event.value: Value of the component
Callback to invoke when a selected value is removed.
onDropdownClickevent.originalEvent: browser event
event.query: Current value of the input field
Callback to invoke to when dropdown button is clicked.
onClickevent: Browser event Callback to invoke on click.
onDblClickevent: Browser eventCallback to invoke on double click.
onMouseDownevent: Browser eventCallback to invoke to when a mouse button is pressed.
onKeyUpevent: Browser eventCallback to invoke to when a key is released.
onKeyPressevent: Browser eventCallback to invoke to when a key is pressed.
onContextMenuevent: Browser eventCallback to invoke on right-click.
onClearevent: Browser eventCallback to invoke when input is cleared by the user.
onShow-Callback to invoke when overlay panel becomes visible.
onHide-Callback to invoke when overlay panel becomes hidden.
Styling

Following is the list of structural style classes

NameElement
p-autocompleteContainer element
p-autocomplete-panelOverlay panel of suggestions.
p-autocomplete-itemsList container of suggestions.
p-autocomplete-itemList item of a suggestion.
p-autocomplete-tokenElement of a selected item in multiple mode.
p-autocomplete-token-iconClose icon element of a selected item in multiple mode.
p-autocomplete-token-labelLabel of a selected item in multiple mode.
Dependencies

None.

Component Scale

Input Style

Ripple Effect

Free Themes

Built-in component themes created by the PrimeReact Theme Designer.

Bootstrap
Blue
Purple
Blue
Purple
Material Design
Indigo
Deep Purple
Indigo
Deep Purple
Material Design Compact
Indigo
Deep Purple
Indigo
Deep Purple
Tailwind
Tailwind Light
Fluent UI
Blue
PrimeOne Design - 2022 NEW
Lara Indigo
Lara Blue
Lara Purple
Lara Teal
Lara Indigo
Lara Blue
Lara Purple
Lara Teal
PrimeOne Design - 2021
Saga Blue
Saga Green
Saga Orange
Saga Purple
Vela Blue
Vela Green
Vela Orange
Vela Purple
Arya Blue
Arya Green
Arya Orange
Arya Purple
Premium Themes

Premium themes are only available exclusively for PrimeReact Theme Designer subscribers and therefore not included in PrimeReact core.

Soho Light
Soho Dark
Viva Light
Viva Dark
Mira
Nano

Legacy Free Themes

Nova
Nova Alt
Nova Accent
Luna Blue
Luna Green
Luna Amber
Luna Pink
Rhea

Premium Create-React-App Templates

Beautifully crafted premium create-react-app application templates by the PrimeTek design team.

Sakai
Atlantis
Freya
Ultima
Diamond
Sapphire
Serenity
Babylon
Avalon
Apollo
Roma