API Reference

Complete reference for NgSelectComponent and related directives and services. Most inputs and outputs below are demonstrated on the Examples pages.

Forms integration

ng-select supports Signal Forms through [formField], Reactive Forms through formControl and formControlName, and Template-driven Forms through ngModel. See the Forms examples for complete examples in that order.

Inputs

Input	Type	Default	Description
[addTag]	boolean | ((term: string) => any | Promise<any>)	false	Allows to create custom options.
addTagText	string	Add item	Set custom text when using tagging
appearance	string	underline	Allows to select dropdown appearance. Set to outline or fill for Material form-field styles (applies only to Material theme)
appendTo	string	null	Append the dropdown overlay to any element using a css selector. Painting and positioning are unaffected; the target determines DOM containment (ancestor-scoped styles, focus enclosure).
ariaLabel	string	-	Sets aria-label on the combobox input.
ariaLabelDropdown	string	Options List	Sets aria-label on the dropdown listbox.
bufferAmount	number	4	Used in virtual scrolling, the bufferAmount property controls the number of items preloaded in the background to ensure smoother and more seamless scrolling.
bindValue	string	-	Object property to use for selected model. By default binds to whole object.
bindLabel	string	label	Object property to use for label. Default label
[closeOnSelect]	boolean	true	Whether to close the menu when a value is selected
[closeOnScroll]	boolean	false	Close the dropdown when the page or an ancestor container scrolls. Default false
clearAllText	string	Clear all	Set custom text for clear all icon title
[clearable]	boolean	true	Allow to clear selected value. Default true
[clearKeepsDisabledOptions]	boolean	true	Keep selected disabled options when the clear button is used. clearModel() always clears them.
[clearOnBackspace]	boolean	true	With an empty search term, Backspace removes the last selected item (clears the value in single mode). Requires [clearable]="true"
[compareWith]	(a: any, b: any) => boolean	undefined	A function to compare the option values with the selected values. The first argument is a value from an option. The second is a value from the selection(model). A boolean should be returned. When not set, options are matched by their bindValue property if set, otherwise by identity or equal labels.
dropdownPosition	bottom | top | left | right | auto	auto	Set the dropdown position on open. auto opens below and flips above when there is not enough room
[fixedPlaceholder]	boolean	true	Keep the placeholder rendered when an item is selected. Visibility is theme-dependent: the default and Ant Design themes hide it once a value is set, the Material theme floats it as a label
[groupBy]	string | Function	null	Allow to group items by key or function expression
[groupValue]	(groupKey: string | any, children: any[]) => string | any	-	Function expression to provide group value
[selectableGroup]	boolean	false	Allow to select group when groupBy is used
[selectableGroupAsModel]	boolean	true	Indicates whether to select all children or group itself
[items]	Array<any>	[]	Items array
[loading]	boolean	false	You can set the loading state from the outside (e.g. async items loading)
loadingText	string	Loading...	Set custom text when for loading items
labelForId	string	-	Id to associate control with label.
[markFirst]	boolean	true	Marks first item as focused when opening/filtering.
[isOpen]	boolean	-	Allows manual control of dropdown opening and closing. true - won't close. false - won't open. Binding a non-null value enables manual mode, where user interaction and open()/close() do nothing.
maxSelectedItems	number	none	When multiple = true, allows to set a limit number of selection.
[hideSelected]	boolean	false	Allows to hide selected items.
[multiple]	boolean	false	Allows to select multiple items.
notFoundText	string	No items found	Set custom text when filter returns empty result
placeholder	string	-	Placeholder text.
removeText	string	Remove	Set custom text prefixed to the option label in the aria-label of the remove icon on selected values (multiple mode)
[searchable]	boolean	true	Allow to search for value. Default true
[readonly]	boolean	false	Prevent user changes while preserving the current selection.
[searchFn]	(term: string, item: any) => boolean	null	Allow to filter by custom search function
[searchWhileComposing]	boolean	true	Whether items should be filtered while composition started
[trackByFn]	(item: any) => any	null	Provide custom trackBy function
[clearSearchOnAdd]	boolean	true	Clears search input when item is selected. Default true. Default false when closeOnSelect is false
[deselectOnClick]	boolean	false	Deselects a selected item when it is clicked in the dropdown. Default false. Default true when multiple is true
[editableSearchTerm]	boolean	false	Allow to edit search query if option selected. Default false. Works only if multiple is false.
[selectOnTab]	boolean	false	Select marked dropdown item using tab. Default false
[tabFocusOnClearButton]	boolean	true	Control tab navigation behavior for the clear button. Default true
[openOnEnter]	boolean	true	Open dropdown using enter. Default true
outsideClickEvent	'click' | 'mousedown'	'click'	Configure which DOM event type is used for outside click detection. Use 'mousedown' to fix issues with backdrop/loading overlays that appear on dropdown open
[popover]	boolean	false	Deprecated — has no effect. The CDK overlay renders in the native Popover API top layer automatically in supporting browsers.
[typeahead]	Subject	-	Custom autocomplete or advanced filter. Emits on typing only; select/close/clear reset the input without emitting (use (close) / (clear) to react to those).
[minTermLength]	number	0	Minimum term length to start a search. Should be used with typeahead
typeToSearchText	string	Type to search	Set custom text when using Typeahead
[virtualScroll]	boolean	false	Enable virtual scroll for better performance when rendering a lot of data
[inputAttrs]	{ [key: string]: string }	-	Pass custom attributes to underlying input element
[ngClass]	string | string[] | Set<string> | Record<string, boolean>	-	Classes bound with [ngClass] are also mirrored onto the dropdown panel.
[panelClass]	string | string[] | Set<string> | Record<string, boolean>	-	Additional CSS classes applied to the dropdown panel. Merged with mirrored host class, [class], and [ngClass] values. Preferred for panel-only styling.
[tabIndex]	number	-	Set tabindex on the inner search input
[preventToggleOnRightClick]	boolean	false	Prevent opening of ng-select on right mouse click
[keyDownFn]	($event: KeyboardEvent) => boolean	(_) => true	Custom handler for control keys (Tab, Enter, Escape, Space, ArrowUp, ArrowDown, Backspace). Runs before the built-in handling; return false to suppress it

Outputs

Output	Description
(add)	Fired when item is added while [multiple]="true". Outputs added item
(blur)	Fired on select blur
(change)	Fired on selection change. Outputs the selected item (an array when [multiple]="true") as the whole item object, not the bindValue-projected model value
(close)	Fired on select dropdown close
(clear)	Fired on clear icon click
(focus)	Fired on select focus
(search)	Fired while typing search term. Outputs search term with filtered items
(open)	Fired on select dropdown open
(remove)	Fired when a selected item is removed (× button, Backspace in multiple mode, or clicking a selected item with [deselectOnClick]). Outputs the removed item
(scroll)	Fired when scrolled (only when [virtualScroll]="true"). Provides the start and end index of the currently available items. Can be used for loading more items in chunks before the user has scrolled all the way to the bottom of the list.
(scrollToEnd)	Fired when scrolled to the end of items. Can be used for loading more items in chunks.
(isOpenChange)	Emits true/false when the dropdown opens or closes. Not emitted in manual mode (a non-null [isOpen] / [(isOpen)] binding), so listen with (isOpenChange) alone.
(itemsChange)	Model output for [(items)]. Emits only when ng-select sets items itself (options declared with <ng-option>)
(bindLabelChange)	Exists because bindLabel is a model(). ng-select only writes it while applying NgSelectConfig defaults in its constructor, before listeners attach, so in practice it never emits; treat [bindLabel] as a one-way input
(bindValueChange)	Exists because bindValue is a model(). ng-select only writes it while applying NgSelectConfig defaults in its constructor, before listeners attach, so in practice it never emits; treat [bindValue] as a one-way input
(appearanceChange)	Exists because appearance is a model(). ng-select only writes it while applying NgSelectConfig defaults in its constructor, before listeners attach, so in practice it never emits; treat [appearance] as a one-way input

Methods

Available on NgSelectComponent when accessed via a template reference variable or @ViewChild.

Name	Description
open	Opens the select dropdown panel
close	Closes the select dropdown panel
toggle	Opens the dropdown panel if closed, closes it if open
focus	Focuses the select element
blur	Blurs the select element
filter	Takes a search term: sets it, filters the items (or pushes it to typeahead) and opens the dropdown
select	Selects an NgOption (e.g. from itemsList.findItem(value))
unselect	Removes an NgOption from the selection
toggleItem	Selects an NgOption, or unselects it if it is already selected and deselectOnClick is on
selectTag	Creates a tag from the current search term (via addTag when it is a function) and selects it
clearModel	Clears the selection, including disabled options, without emitting (clear). No-op when clearable is false

ng-option

Inputs of NgOptionComponent, used to declare options in HTML. The element content is the option label.

Input	Type	Default	Description
[value]	any	undefined	Value bound to the option
[disabled]	boolean	false	Whether the option is disabled and not selectable

Template directives

Customize every part of the select with ng-template directives — see live examples on the Templates page.

Directive	Customizes
ng-label-tmp	Label of each selected item (single select, or multiple select without ng-multi-label-tmp)
ng-multi-label-tmp	Selected items (multi select)
ng-option-tmp	Option rows in the dropdown
ng-optgroup-tmp	Group headers when groupBy is used
ng-header-tmp	Dropdown header
ng-footer-tmp	Dropdown footer
ng-placeholder-tmp	Placeholder
ng-notfound-tmp	"No items found" message
ng-typetosearch-tmp	"Type to search" message
ng-loadingtext-tmp	Loading message
ng-loadingspinner-tmp	Loading spinner
ng-clearbutton-tmp	Clear button
ng-tag-tmp	Tag row when addTag is enabled

Other

Name	Type	Description
[ngOptionHighlight]	directive	Highlights search term in option. Accepts search term. Should be used on option element. README
NgSelectConfig	configuration	Configuration provider for the NgSelect component. You can inject this service and provide application wide configuration. See NgSelectConfig.

NgSelectConfig

Application-wide defaults, applied when the matching ng-select input is not set.

Property	Type	Default	Description
placeholder	string	-	Placeholder text
fixedPlaceholder	boolean	true	Default for [fixedPlaceholder]
notFoundText	string	No items found	Text when filter returns empty result
typeToSearchText	string	Type to search	Text when using Typeahead
addTagText	string	Add item	Text when using tagging
loadingText	string	Loading...	Text when loading items
clearAllText	string	Clear all	Clear all icon title
removeText	string	Remove	Prefix of the remove icon aria-label (multiple mode)
ariaLabelDropdown	string	Options List	aria-label of the dropdown listbox
disableVirtualScroll	boolean	true	Disables virtual scroll unless [virtualScroll] is set
openOnEnter	boolean	true	Open dropdown using enter
appendTo	string	-	Default appendTo css selector for every select
bindValue	string	-	Default bindValue
bindLabel	string	-	Default bindLabel (falls back to label)
appearance	string	underline	Default appearance
clearSearchOnAdd	boolean	-	Default [clearSearchOnAdd] (falls back to closeOnSelect)
deselectOnClick	boolean	-	Default [deselectOnClick] (falls back to multiple)
tabFocusOnClear	boolean	true	Default [tabFocusOnClearButton]
outsideClickEvent	'click' | 'mousedown'	'click'	Default outsideClickEvent
closeOnScroll	boolean	false	Default [closeOnScroll]