Info

File

packages/components/eui-autocomplete/eui-autocomplete.component.ts

Description

eui-autocomplete component with dropdown suggestions, optional chip display for multiple selections, and comprehensive keyboard navigation. Provides type-ahead functionality with filtering, grouping, sorting, and async data support. Implements ControlValueAccessor for Angular forms integration with validation support. eui-autocomplete supports single or multiple selection modes with chips for visual representation of selected items. Built on Angular CDK Overlay for positioning and virtual scrolling for performance with large datasets. eui-autocomplete includes accessibility features with ARIA attributes, live announcer, and keyboard navigation.

Basic single selection

Example :

<eui-autocomplete [autocompleteData]="fruits" placeholder="Select a fruit"></eui-autocomplete>

Multiple selection with chips

Example :

<eui-autocomplete
  [autocompleteData]="countries"
  [hasChips]="true"
  [chipsPosition]="'top'"
  (selectionChange)="onSelectionChange($event)">
</eui-autocomplete>

With grouping and async data

Example :

<eui-autocomplete
  [autocompleteData]="cities"
  [groupBy]="'metadata.continent'"
  [isAsync]="true"
  [isLoading]="loading">
</eui-autocomplete>

In reactive form with validation

Example :

<eui-autocomplete
  [autocompleteData]="options"
  formControlName="selection"
  [isForceSelection]="true">
</eui-autocomplete>

Example :

fruits: EuiAutoCompleteItem[] = [
  { id: 1, label: 'Apple' },
  { id: 2, label: 'Banana' },
  { id: 3, label: 'Orange' }
];

onSelectionChange(items: EuiAutoCompleteItem[]): void {
  console.log('Selected:', items);
}

Accessibility

Uses ARIA live announcer to announce option navigation for screen readers
Keyboard navigation: Arrow Up/Down to navigate options, Enter to select, Escape to close
Tab key closes panel and optionally adds chip (with isAddOnBlur)
Backspace removes last chip when input is empty (chipsPosition='inside')
aria-required attribute automatically set when used with Validators.required
Each option has role="option" for proper screen reader identification
Panel positioning adjusts automatically to stay within viewport

Notes

Each EuiAutoCompleteItem must have unique id and label properties
Use hasChips for multiple selection mode, omit for single selection
chipsPosition options: 'top' (default), 'bottom', 'inside' (chips within input)
matching options: 'contains' (default) or 'startWith' for filtering behavior
Set isForceSelection to require selection from available options only
isFreeValueAllowed (default true) allows custom values not in the list
Virtual scrolling automatically handles large datasets efficiently
groupBy accepts nested property paths (e.g., 'metadata.category.name')
Use isAsync with dynamic data loading, update autocompleteData when ready
Chips can be drag-and-dropped when isChipsDragAndDrop is enabled
Panel width defaults to input width, override with panelWidth property

Implements

OnInit OnDestroy ControlValueAccessor OnChanges AfterViewInit DoCheck

Metadata

changeDetection	`ChangeDetectionStrategy.OnPush`
encapsulation	`ViewEncapsulation.None`
HostDirectives	`BaseStatesDirective` Inputs : euiSecondary euiSuccess euiInfo euiWarning euiDanger
selector	`eui-autocomplete, input[euiAutocomplete]`
imports	`DragDropModule` `NgTemplateOutlet` `AsyncPipe` `ReactiveFormsModule` `OverlayModule` `ScrollingModule` `A11yModule` `EuiAutocompleteOptionComponent` `EuiAutocompleteOptionGroupComponent` `EUI_INPUT_TEXT` `EUI_CHIP_LIST` `EUI_CHIP` `EUI_ICON` `EUI_BUTTON` `EuiTruncatePipe` `EuiTooltipDirective`
templateUrl	`./eui-autocomplete.component.html`
styleUrl	`./eui-autocomplete.scss`

Index

Constructor

constructor()

Inputs

autocompleteDataSelected

Type : EuiAutoCompleteItem[]

Default value : []

Sets the options that will be selected by default.

autocompleteData

Default value : []

Datas to be used in the autocomplete.

chipsLabelTruncateCount

Default value : null, { transform: numberAttribute }

Whether the chips label length is limited by the value of this option.

chipsPosition

Type : "top" | "bottom" | "inside"

Default value : 'top'

chipsSortOrder

Type : "ASC" | "DESC"

Default value : 'ASC'

Sets the sort criteria of the chips.

classList

Type : string

Default value : null

Sets a CSS class to be added on the options panel container.

groupBy

Type : string

Sets a grouping among the options.

hasChips

Default value : false, { transform: booleanAttribute }

Whether autocomplete will display the selected values with chips.

inputId

Sets the id on the text input.

isAddOnBlur

Default value : false, { transform: booleanAttribute }

In combination with hasChips. Whether the chip is added when the text input is blurred.

isAsync

Default value : false, { transform: booleanAttribute }

Whether autocomplete will get the data asynchronously.

isChipsDragAndDrop

Default value : false, { transform: booleanAttribute }

Whether the chips can be drag and dropped.

isChipsRemovable

Default value : true, { transform: booleanAttribute }

Whether the chip can be removed from the selection. When a chip is removed, its value goes back in the panel.

isChipsSorted

Default value : false, { transform: booleanAttribute }

Whether this chip is sorted on their label.

isDuplicateValueAllowed

Default value : false, { transform: booleanAttribute }

Whether the chips can have multiple times the same value. With this option, the value is not removed from the panel when choosen.

isForceSelection

Default value : false, { transform: booleanAttribute }

In combination with hasChips and isFreeValueAllowed=false. Whether the text input is empty after blurring when no value has been selected in the panel.

isFreeValueAllowed

Default value : true, { transform: booleanAttribute }

In combination with hasChips. Whether the user can add a value, which is not part of the options, to craete a chip.

isGroupSorted

Default value : true, { transform: booleanAttribute }

Whether the grops of items are sorted on their label.

isItemsSorted

Default value : false, { transform: booleanAttribute }

Whether this item in the panel is sorted on their label.

isLoading

Default value : false, { transform: booleanAttribute }

Whether loading spinner is displayed in text input.

isMaxVisibleChipsOpened

Default value : false, { transform: booleanAttribute }

In combination with maxVisibleChipsCount. Whether all chips are shown by default.

isReadonly

Default value : false, { transform: booleanAttribute }

Whether autocomplete is in readonly mode.

itemsSortOrder

Type : "ASC" | "DESC"

Default value : 'ASC'

In combination with isChipsSorted. Sets the sort criteria of the options in the panel.

matching

Default value : 'contains'

Sets the way the options should be retrieved.

maxVisibleChipsCount

Default value : null, { transform: numberAttribute }

Whether a limited amount, defined by this option, is used to display the chips.

panelWidth

Type : string | number

Sets the width of the options panel.

placeholder

Type : string

Default value : ''

Sets the placeholder of the text input.

toggleLinkLessLabel

Type : string

Default value : null

In combination with maxVisibleChipsCount, sets the label of the 'less label' button, if not provided an arrow left icon will be displayed only.

toggleLinkMoreLabel

Type : string

Default value : null

In combination with maxVisibleChipsCount, sets the label of the 'more label' button, if not provided an arrow right icon will be displayed only.

visibleOptions

Default value : 5, { transform: numberAttribute }

Sets the maximum number of options that will be visible in the autocomplete panel.

Outputs

chipDragRelease

Type : EuiChipDragDrop

Event emitted when a chip drag is released.

chipDragStart

Type : EuiChipDragDrop

Event emitted when a chip drag starts.

chipDrop

Type : EuiChipDragDrop

Event emitted when a chip is dropped.

clear

Event emitted when the text input is cleared.

inputBlur

Event emitted when the text input is blurred.

inputChange

Type : string

Event emitted when the value of the text input changes.

inputFocus

Event emitted when the text input gets the focus.

itemAdd

Type : EuiAutoCompleteItem

Event emitted when an option is selected.

itemRemove

Type : EuiAutoCompleteItem

Event emitted when an option is removed.

panelClose

Event emitted when the panel is closed.

panelOpen

Event emitted when the panel is opened.

selectionChange

Type : EuiAutoCompleteItem[]

Event emitted when an option is selected or when the selection is modified.

HostBindings

class

Type : string

Computes and returns the CSS classes for the component based on its current state.

Methods

Public add

add(value: string)

Method called when an option is added through the text input.

Parameters :

Name	Type	Optional	Description
value	`string`	No	Value to add

Returns : void

Public closePanel

closePanel()

Closes the autocomplete panel.

Returns : void

Public onBlur

onBlur()

Text input blur handler.

Returns : void

Public onChipDragReleased

onChipDragReleased(e: CdkDragRelease)

Called when a chip is released for reordering or from a source to another.

Parameters :

Name	Type	Optional	Description
e	`CdkDragRelease`	No	Object containing the chip released.

Returns : void

Public onChipDragStarted

onChipDragStarted(e: CdkDragStart)

Called when a chip is dragged for reordering or from a source to another.

Parameters :

Name	Type	Optional	Description
e	`CdkDragStart`	No	Object containing the chip dragged.

Returns : void

Public onChipDropped

onChipDropped(e: CdkDragDrop)

Called when a chip is dropped for reordering or from a source to another.

Parameters :

Name	Type	Optional	Description
e	`CdkDragDrop<any[]>`	No	Object containing the chip dropped.

Returns : void

Public onChipRemove

onChipRemove(chip: EuiChip)

Called when a chip is removed.

Parameters :

Name	Type	Optional
chip	`EuiChip`	No

Returns : void

Public onClear

onClear()

Returns : void

Public onFocus

onFocus()

Text input focus handler.

Returns : void

Public onOptionSelected

onOptionSelected(e: EuiAutoCompleteItem)

Method called when an option is selected.

Parameters :

Name	Type	Optional	Description
e	`EuiAutoCompleteItem`	No	Selected option

Returns : void

Public openPanel

openPanel()

Method that creates and opens the panel containing autocomplete options.

Returns : void

Public optionsTrackByFn

optionsTrackByFn(index: number, item: EuiAutoCompleteItem)

Parameters :

Name	Type	Optional
index	`number`	No
item	`EuiAutoCompleteItem`	No

Returns : string | number

Public registerOnChange

registerOnChange(fn: () => void)

Parameters :

Name	Type	Optional
fn	`function`	No

Returns : void

Public registerOnTouched

registerOnTouched(fn: () => void)

Parameters :

Name	Type	Optional
fn	`function`	No

Returns : void

Public setDisabledState

setDisabledState(isDisabled: boolean)

Parameters :

Name	Type	Optional
isDisabled	`boolean`	No

Returns : void

Public toggleTags

toggleTags()

Returns : void

Public writeValue

writeValue(value: EuiAutoCompleteItem | EuiAutoCompleteItem[])

Parameters :

Name	Type	Optional
value	`EuiAutoCompleteItem \| EuiAutoCompleteItem[]`	No

Returns : void

Properties

Public autocompleteControl

Type : unknown

Default value : new FormControl<string>('')

Public autocompleteOptGroupTemplate

Type : TemplateRef<literal type>

Public autocompleteOptions

Type : unknown

Default value : signal<EuiAutoCompleteItem[]>(this.autocompleteData())

Public autocompleteOptionTemplate

Type : TemplateRef<literal type>

Public chips

Type : EuiChip[]

Default value : []

Public distinctOptionGroups

Type : string[]

Public globalOptionIndex

Type : number

Default value : 0

Public groupedOptions

Type : unknown

Default value : new BehaviorSubject<{ [id: string]: { options: EuiAutoCompleteItem[], ancestorLength: number } }>({})

input

Type : ElementRef

Decorators :


                            @ViewChild('input', {read: ElementRef})

inputContainerRef

Type : ElementRef

Decorators :


                            @ViewChild('inputContainerRef')

Public isDisabled

Type : unknown

Default value : false

Public Readonly isVisibleChipsOpened

Type : Signal<boolean>

Public itemSize

Type : number

Default value : 40

Public selectedOptionIndex

Type : number

Default value : 0

templatePortalContent

Type : TemplateRef<ElementRef>

Decorators :


                            @ViewChild('templatePortalContent')

templates

Type : QueryList<EuiTemplateDirective>

Decorators :


                            @ContentChildren(EuiTemplateDirective)

virtualScrolling

Type : CdkVirtualScrollViewport

Decorators :


                            @ViewChild('virtualScrolling')

Accessors

cssClasses

getcssClasses()

Computes and returns the CSS classes for the component based on its current state.

Returns : string

isChipsPositionInside

getisChipsPositionInside()

cdkVirtualScrollViewport

getcdkVirtualScrollViewport()

Calculates the height that the virtual scroll need to have.

Returns : number

isOpen

getisOpen()

Returns the opening state of the panel.

Returns : boolean

hasOptionsResult

gethasOptionsResult()

Checks if autocomplete options are available.

Returns : boolean

File

Description

Basic single selection

Multiple selection with chips

With grouping and async data

In reactive form with validation

Accessibility

Notes

Implements

Metadata

Index

Properties

Methods

Inputs

Outputs

HostBindings

Accessors

Constructor

Inputs

Outputs

HostBindings

Methods

Properties

Accessors

results matching ""

No results matching ""