# Value Binding

The value of the ComboBox can either be a [primitive (strings, numbers, or other)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Primitive_values) or a [complex value (objects)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Objects).

To set the value, apply any of the following approaches:

* Use the [`value`](https://www.telerik.com/kendo-angular-ui-develop/components/dropdowns/api/comboboxcomponent#value) property. If the value is set through the `value` property, you have to hook up to the [`valueChange`](https://www.telerik.com/kendo-angular-ui-develop/components/dropdowns/api/comboboxcomponent#valuechange) event and manually update the value of the `value` property.
* Use the [`ngModel`](https://angular.dev/guide/forms) value binding. If the value is set by the `ngModel` value binding, the framework will automatically update the corresponding field from the model after the value of the component changes.
* Use the [`formControlName`](https://angular.dev/api/forms/FormControlName) value binding, which is available in the [Reactive forms](https://angular.dev/guide/forms/reactive-forms). If the value is set by the `formControlName` value binding, the framework will automatically update the corresponding field from the form model after the value of the component changes.

> - The ComboBox does not support the simultaneous usage of the `value` property and the `ngModel` value binding.
> - The ComboBox does not support values, which contain `\n` new line characters. The regular `input` HTML DOM element, which the ComboBox uses internally treats `\n` as a regular whitespace. Therefore, when the component compares the value of the `input` element with the data item that is selected by the user, the two values differ. The value of the `input` element is actually not present in the data of the component and the ComboBox does not recognize it. To handle such issues, map the incoming data so that it contains regular whitespaces only.

When binding the ComboBox, the component provides options for:

* [Using primitive values (string, numbers, or other)](https://www.telerik.com/kendo-angular-ui-develop/components/dropdowns/combobox/value-binding#primitive-values)
* [Using complex values (objects)](https://www.telerik.com/kendo-angular-ui-develop/components/dropdowns/combobox/value-binding#object-values)
* [Using primitive values from object fields](https://www.telerik.com/kendo-angular-ui-develop/components/dropdowns/combobox/value-binding#primitive-values-from-object-fields)
* [Using custom values](https://www.telerik.com/kendo-angular-ui-develop/components/dropdowns/combobox/custom-values)
* [Handling invalid value errors](https://www.telerik.com/kendo-angular-ui-develop/components/dropdowns/combobox/value-binding#invalid-value-errors)
* [Handling unresolved text](https://www.telerik.com/kendo-angular-ui-develop/components/dropdowns/combobox/value-binding#unresolved-text)

## Primitive Values

If the ComboBox is bound to a dataset of primitives, its value will be a primitive of the same type.

Primitive data types include:

* `String`
* `Number`
* `Undefined`
* `Null`

The following snippet shows how to set a pre-selected value using the `[value]` input.

```html app.component.html
<kendo-combobox
    [data]="sizes"
    [value]="selectedSize">
</kendo-combobox>
```

```typescript app.component.ts
public sizes: string[] = ['Small', 'Medium', 'Large'];
public selectedSize = 'Medium';
```

The following example demonstrates primitive value binding with the ComboBox.

[Demo Source](https://demos.telerik.com/kendo-angular-ui/demos/dropdowns/combobox/value_binding/source.txt)

## Object Values

If the ComboBox is bound to a dataset of objects, its value will be an object of the same type.

> When the selected item is an object, always specify `valueField`. If you do not set a value for the field, the ComboBox will compare the items by reference, which may complicate debugging. For example, the selected value will not be applied, if it does not reference the exact passed `data` object.

The following snippet shows how to use `[value]` with an object dataset.

```html app.component.html

<kendo-combobox
    [data]="countries"
    textField="name"
    valueField="code"
    [value]="selectedCountry">
</kendo-combobox>
```

```typescript app.component.ts
public countries = [
    { code: 'US', name: 'United States' },
    { code: 'GB', name: 'United Kingdom' },
    { code: 'DE', name: 'Germany' }
];
public selectedCountry = this.countries[0];
```

The following example demonstrates object value binding with the ComboBox.

[Demo Source](https://demos.telerik.com/kendo-angular-ui/demos/dropdowns/combobox/value_binding/object_values/source.txt)

## Primitive Values from Object Fields

If you bind the ComboBox to a dataset of objects and the [`valuePrimitive`](https://www.telerik.com/kendo-angular-ui-develop/components/dropdowns/api/comboboxcomponent#valueprimitive) property is set to `true`, the value of the component will be extracted from the [`valueField`](https://www.telerik.com/kendo-angular-ui-develop/components/dropdowns/api/comboboxcomponent#valuefield) of the objects. Use this approach to store only a scalar identifier (for example, a country code) rather than the full object.

The following snippet shows how to store only the `code` string. This pattern is common when a form field needs to send a country code or status ID to an API rather than a full object.

```html app.component.html

<kendo-combobox
    [data]="countries"
    textField="name"
    valueField="code"
    [valuePrimitive]="true"
    [value]="selectedCode">
</kendo-combobox>
```

```typescript app.component.ts
public countries = [
    { code: 'US', name: 'United States' },
    { code: 'GB', name: 'United Kingdom' },
    { code: 'DE', name: 'Germany' }
];
public selectedCode = 'US';
```

The following example demonstrates how to bind a ComboBox to object data while keeping the selected value as a primitive.

[Demo Source](https://demos.telerik.com/kendo-angular-ui/demos/dropdowns/combobox/value_binding/primitive_values/source.txt)

## Invalid Value Errors

If the value, which is assigned through the `[value]` or `[(ngModel)]` inputs, does not match the expected type, the ComboBox throws a JavaScript error.

In the following example, the component has both its `[valueField]` and `[textField]` specified, which implies that the `[data]` will contain objects. Because the `[valuePrimitive]` is not explicitly set to `true`, the ComboBox expects an object value. Instead, a number is provided and, as a result, a JavaScript exception occurs.

[Demo Source](https://demos.telerik.com/kendo-angular-ui/demos/dropdowns/combobox/value_binding_error/source.txt)

To fix the JavaScript issue, either:

* Change the value type, or
* Update the settings of the component.

The following table lists the valid configuration scenarios.

| Value     | \[Data]    | \[ValuePrimitive]                             |
| :-------- | :--------- | :-------------------------------------------- |
| primitive | primitives | Not set (automatically calculated as `true`)  |
| object    | objects    | Not set (automatically calculated as `false`) |
| primitive | objects    | `true`  (manually set by the developer)       |

## Unresolved Text

The text value, which is assigned through the `[value]` or `[(ngModel)]` inputs and which is not found in the dataset will not be resolved. Such values also include object values that contain the `textField` property.

The following example demonstrates how to merge the assigned value with the dataset and ensure that its text will be properly extracted and displayed.

[Demo Source](https://demos.telerik.com/kendo-angular-ui/demos/dropdowns/combobox/unresolved_text/source.txt)

## Suggested Links

* [API Reference of the ComboBox](https://www.telerik.com/kendo-angular-ui-develop/components/dropdowns/api/comboboxcomponent)