ComboBoxComponent
Represents the Kendo UI ComboBox component for Angular.
@Component({
selector: 'my-app',
template: `
<kendo-combobox [data]="listItems">
</kendo-combobox>
`
})
class AppComponent {
public listItems: Array<string> = ["Item 1", "Item 2", "Item 3", "Item 4"];
}
Selector
kendo-combobox
Export Name
Accessible in templates as #kendoComboBoxInstance="kendoComboBox"
Inputs
allowCustom
boolean
Specifies whether the ComboBox allows user-defined values that are not present in the dataset
(more information and examples).
Defaults to false
.
clearButton
boolean
If set to true
, renders a button on hovering over the component.
Clicking this button resets the value of the component to undefined
and triggers the change
event.
disabled
boolean
Sets the disabled state of the component.
filterable
boolean
Enables the filtering functionality.
If set to true
, the component emits the filterChange
event.
listHeight
number
Sets the height of the suggestions list. By default, listHeight
is 200px.
The
listHeight
property affects only the list of suggestions and not the whole popup container. To set the height of the popup container, usepopupSettings.height
.
loading
boolean
Sets and gets the loading state of the ComboBox.
placeholder
string
The hint that is displayed when the component is empty.
readonly
boolean
Sets the read-only state of the component.
suggest
boolean
Enables the auto-completion of the text based on the first data item.
tabindex
number
Specifies the tabindex
of the component.
textField
string
Sets the data item field that represents the item text. If the data contains only primitive values, do not define it.
The
textField
property can be set to point to a nested property value - e.g.category.name
.
valueField
string
Sets the data item field that represents the item value. If the data contains only primitive values, do not define it.
The
valueField
property can be set to point to a nested property value - e.g.category.id
.
valueNormalizer
(text: Observable<string>) => Observable<any>
A user-defined callback which returns normalized custom values.
Typically used when the data items are different from type string
.
import { map } from 'rxjs/operators';
@Component({
selector: 'my-app',
template: `
<kendo-combobox
[allowCustom]="true"
[data]="listItems"
textField="text"
valueField="value"
[valueNormalizer]="valueNormalizer"
(valueChange)="onValueChange($event)"
>
</kendo-combobox>
`
})
class AppComponent {
public listItems: Array<{ text: string, value: number }> = [
{ text: "Small", value: 1 },
{ text: "Medium", value: 2 },
{ text: "Large", value: 3 }
];
public onValueChange(value) {
console.log("valueChange : ", value);
}
public valueNormalizer = (text$: Observable<string>) => text$.pipe(map((text: string) => {
return { ProductID: null, ProductName: text };
}));
}
data
any
Sets the data of the ComboBox.
The data has to be provided in an array-like list.
fillMode
Sets the fillMode of the component.
The possible values are:
flat
solid
(default)outline
none
itemDisabled
Defines a Boolean function that is executed for each data item in the component (see examples). Determines whether the item will be disabled.
popupSettings
Configures the popup of the ComboBox.
The available options are:
animate: Boolean
—Controls the popup animation. By default, the open and close animations are enabled.width: Number | String
—Sets the width of the popup container. By default, the width of the host element is used. If set toauto
, the component automatically adjusts the width of the popup and no item labels are wrapped. Theauto
mode is not supported when virtual scrolling is enabled.height: Number
—Sets the height of the popup container.popupClass: String
—Specifies a list of CSS classes that are used to style the popup.appendTo: "root" | "component" | ViewContainerRef
—Specifies the component to which the popup will be appended.
rounded
Sets the border radius of the component.
The possible values are:
small
medium
(default)large
full
none
size
Sets the size of the component.
The possible values are:
small
medium
(default)large
none
value
any
Sets the value of the ComboBox.
It can either be of the primitive (string, numbers) or of the complex (objects) type.
To define the type, use the valuePrimitive
option.
All selected values which are not present in the dataset are considered custom values. When the
Enter
key is pressed or the component loses focus, custom values get dismissed unlessallowCustom
is set totrue
.
valuePrimitive
boolean
Specifies the type of the selected value.
If set to true
, the selected value has to be of the primitive type
(more information and example).
virtual
boolean | VirtualizationSettings
Enables the virtualization functionality.
Fields
isOpen
boolean
Returns the current open state of the popup.
Events
close
EventEmitter<PreventableEvent>
Fires each time the popup is about to close. This event is preventable. If you cancel it, the popup will remain open.
closed
EventEmitter<any>
Fires after the popup has been closed.
filterChange
EventEmitter<any>
Fires each time the user types in the input field. You can filter the source based on the passed filtration value (see example).
blur
EventEmitter<any>
Fires each time the ComboBox gets blurred.
focus
EventEmitter<any>
Fires each time the user focuses the ComboBox.
open
EventEmitter<PreventableEvent>
Fires each time the popup is about to open. This event is preventable. If you cancel it, the popup will remain closed.
opened
EventEmitter<any>
Fires after the popup has been opened.
selectionChange
EventEmitter<any>
Fires each time an item selection is changed (see example).
valueChange
EventEmitter<any>
Fires each time the value is changed—
when the component is blurred or the value is cleared through the Clear button
(see example).
When the value of the component is programmatically changed to ngModel
or formControl
through its API or form binding, the valueChange
event is not triggered because it
might cause a mix-up with the built-in valueChange
mechanisms of the ngModel
or formControl
bindings.
Methods
blur
Blurs the ComboBox.
focus
Focuses the ComboBox.
focusItemAt
Focuses a specific item of the ComboBox based on a provided index. If null or invalid index is provided the focus will be removed.
Parameters
index
number
reset
Resets the value of the ComboBox.
If you use the reset
method to clear the value of the component,
the model will not update automatically and the selectionChange
and valueChange
events will not be fired.
toggle
Toggles the visibility of the popup. If you use the toggle
method to open or close the popup,
the open
and close
events will not be fired.
Parameters
open?
boolean
The state of the popup.