Component · v2.7.0

NgbTypeaheadComponent

Searchable selection control with Angular forms integration, multiple selection, chips, custom option templates and fixed-height virtual scrolling.

Import

import { NgbTypeaheadComponent } from '@angular-bootstrap/ngbootstrap';

Selector:ngb-typeahead

Usage notes

Import ReactiveFormsModule for [formControl] or FormsModule for [(ngModel)]. A single value is item.value when defined, otherwise the item object; clearing yields null. Multi-select yields an array.
Use selectionChange to receive item objects regardless of the form-value shape. Disable through the Angular form control; disabled is not a bindable component input.
Custom option templates receive let-item, let-query="query", let-selected="selected" and let-index="index". itemTemplate overrides the projected template.
Virtual scrolling covers already supplied fixed-height options. Set limit to 0 when the full supplied result set should be available; handle completeMethod and onLazyLoad in application code for remote data.

Declaration

class NgbTypeaheadComponent implements AfterViewInit, OnChanges, OnDestroy, ControlValueAccessor

Inputs

`inputId`

ID of the native input, for an external label's for attribute.

inputId: string

Default:''

`ariaLabel`

Accessible name of the native input when no visible label is used.

ariaLabel: string

Default:''

`ariaLabelledBy`

Space-separated IDs of elements that label the native input.

ariaLabelledBy: string

Default:''

`ariaDescribedBy`

Space-separated IDs of instructions or errors for the native input.

ariaDescribedBy: string

Default:''

`data`

Available options. Local matching is case-insensitive against label. Replace this array when supplying remote results.

data: NgbTypeaheadItem[]

Default:[]

`debounceTime`

Delay in milliseconds before local filtering and completeMethod. Zero or negative values process immediately.

debounceTime: number

Default:200

`characterTyped`

Minimum query length for normal filtering. The dropdown button bypasses this threshold.

characterTyped: number

Default:1

`limit`

Maximum matching results after local filtering. Set 0 for no limit, including when virtualizing a larger result set.

limit: number

Default:10

`selectExact`

Automatically selects when exactly one filtered result remains. This is not a strict full-label equality check.

selectExact: boolean

Default:false

`multiSelect`

Allows multiple selected items and makes the form value an array.

multiSelect: boolean

Default:false

`matchSelection`

Requires a case-insensitive full-label match when committing text on close; unmatched text is cleared.

matchSelection: boolean

Default:false

`showDropdownButton`

Shows a button that toggles suggestions and can open results without a search term.

showDropdownButton: boolean

Default:false

`showClearButton`

Shows a button that clears query and selection and closes the panel.

showClearButton: boolean

Default:false

`updateOnBlur`

Commits typed chip tokens on blur when chips and multiSelect are enabled. In single mode, may create a free-text item when closing without a selection, unless matchSelection is enabled.

updateOnBlur: boolean

Default:false

`updateOnTab`

Controls committing a typed chip on Tab in chips + multiSelect mode. In other modes, Tab can still select the active suggestion.

updateOnTab: boolean

Default:true

`separator`

Token separator or separators used by chips + multiSelect mode.

separator: string | string[]

Default:','

`chips`

Displays selected items as removable chips when multiSelect is enabled.

chips: boolean

Default:false

`vScroll`

Renders a fixed-height window of the filtered results. Does not fetch data automatically; limit still applies.

vScroll: boolean

Default:false

`vItemSize`

Virtual row height in pixels. Keep custom option templates at this height.

vItemSize: number

Default:40

`itemTemplate`

Explicit option TemplateRef; takes precedence over a projected ng-template. Context: $implicit/item, query, selected and visible-window index. The shipped declaration uses any.

itemTemplate?: any

`i18n`

Overrides placeholder, no-results and action labels. Omitted values use English fallbacks.

i18n?: NgbTypeaheadI18n

Outputs

`completeMethod`

Emits the typed query after debounce. Applications own remote fetching, cancellation and assignment to data.

completeMethod: EventEmitter<string>

`onSelect`

Emits an item when selected.

onSelect: EventEmitter<NgbTypeaheadItem>

`onUnselect`

Emits an item when removed or replaced through selection interactions.

onUnselect: EventEmitter<NgbTypeaheadItem>

`onAdd`

Emits an item created from free text or committed as a chip token.

onAdd: EventEmitter<NgbTypeaheadItem>

`onFocus`

Emits the native input focus event.

onFocus: EventEmitter<FocusEvent>

`onBlur`

Emits the native input blur event and marks the form control touched.

onBlur: EventEmitter<FocusEvent>

`onDropdownClick`

Emits the dropdown-button mouse event.

onDropdownClick: EventEmitter<MouseEvent>

`onClear`

Emits the clear-button event. Calling clearSelection directly does not emit this event.

onClear: EventEmitter<Event>

`onInputKeydown`

Emits the input keydown event before built-in key handling.

onInputKeydown: EventEmitter<KeyboardEvent>

`onKeyUp`

Emits the native input keyup event.

onKeyUp: EventEmitter<KeyboardEvent>

`onShow`

Emits when the suggestion panel opens. Programmatic opening creates a show Event.

onShow: EventEmitter<Event>

`onHide`

Emits when the suggestion panel closes. Programmatic closing creates a hide Event.

onHide: EventEmitter<Event>

`onLazyLoad`

Emits when scrolling within 48px of the panel bottom. No range payload or automatic request deduplication is provided.

onLazyLoad: EventEmitter<void>

`selectedItems`

Emits the selected item array; retained alongside selectionChange.

selectedItems: EventEmitter<NgbTypeaheadItem[]>

`selectionChange`

Emits selected item objects. This differs from the Angular form value, which uses each item’s value when defined.

selectionChange: EventEmitter<NgbTypeaheadItem[]>

`onChange`

Emits the raw typed text. This is an output, distinct from the ControlValueAccessor change callback.

onChange: EventEmitter<string>

`onScrollEvent`

Legacy void output emitted when the result panel scrolls.

onScrollEvent: EventEmitter<void>

Properties

`projectedItemTemplate`

First projected TemplateRef, used when itemTemplate is absent. This is a content query, not an input.

projectedItemTemplate?: any

`scroller`

scroller: ElementRef<HTMLElement>

`inputEl`

inputEl?: ElementRef<HTMLInputElement>

`itemButtons`

itemButtons?: QueryList<ElementRef<HTMLButtonElement>>

`disabled`

Current forms-disabled state. It is not an @Input; disable the bound FormControl or use the value-accessor method.

disabled: boolean

Default:false

`query`

query: string

Default:''

`filtered`

filtered: NgbTypeaheadItem[]

Default:[]

`visible`

visible: NgbTypeaheadItem[]

Default:[]

`selected`

selected: NgbTypeaheadItem[]

Default:[]

`overlayVisible`

overlayVisible: boolean

Default:false

`activeIndex`

activeIndex: number

Default:-1

`overlayId`

readonly overlayId: string

Default:`ngb-typeahead-overlay-${Math.random().toString(36).slice(2)}`

`viewportHeight`

viewportHeight: number

Default:240

`itemHeight`

itemHeight: number

Default:40

`beforePadding`

beforePadding: number

Default:0

`afterPadding`

afterPadding: number

Default:0

`activeDescendantId`

get activeDescendantId(): string | null

`showNoResults`

get showNoResults(): boolean

`displayQuery`

get displayQuery(): string

`selectionSummary`

get selectionSummary(): string

`resolvedItemTemplate`

get resolvedItemTemplate(): any

`trackById`

Returns item.id for option rendering identity.

trackById: (_: number, item: NgbTypeaheadItem) => string | number

Referenced types

Source: src/typeahead/src/typeahead/typeahead.component.ts in the installed @angular-bootstrap/ngbootstrap package. Angular compiler metadata and private members are omitted.

Import

Usage notes

Declaration

Inputs

Outputs

Properties

Methods

Referenced types