# Value Binding

The MultiSelect value can be an array of either [primitive (strings, numbers, or other)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Primitive_values) or [complex values (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/components/dropdowns/api/multiselectcomponent#value) property. If the value is set through the `value` property of the MultiSelect, you have to hook up to the [`valueChange`](https://www.telerik.com/kendo-angular-ui/components/dropdowns/api/multiselectcomponent#valuechange) event and manually update 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 automatically will 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 available in the [Reactive forms](https://angular.dev/guide/forms/reactive-forms). If the value is set by the `formControlName` value binding, the framework automatically will update the corresponding field from the form model after the value of the component changes.

> - The MultiSelect does not support the simultaneous usage of the `value` property and the `ngModel` value binding.
> - The MultiSelect does not support values which contain `\n` new line characters. The regular `input` HTML DOM element which the MultiSelect 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 MultiSelect does not recognize it. To handle such issues, map the incoming data so that it contains regular whitespaces only.

When binding the MultiSelect value, the component provides options for:

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

## Primitive Values

If the MultiSelect is bound to a dataset of primitive values, its value will be an array of primitives of the same type.

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

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

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

The following example demonstrates primitive value binding with the MultiSelect.

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

## Object Values

If the MultiSelect 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 a set value for the field, the MultiSelect 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 object data. Pre-selected items must reference the same instances present in `data` — assigning a new object literal with identical fields will not match because the component compares by reference when `valuePrimitive` is not set.

```html app.component.html

<kendo-multiselect
    [data]="categories"
    textField="name"
    valueField="id"
    [value]="selectedCategories">
</kendo-multiselect>
```

```typescript app.component.ts
public categories = [
    { id: 1, name: 'Electronics' },
    { id: 2, name: 'Clothing' },
    { id: 3, name: 'Books' }
];
public selectedCategories = [this.categories[0]];
```

The following example demonstrates object value binding with the MultiSelect.

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

## Primitive Values from Object Fields

If the MultiSelect is bound to a dataset of complex objects and the [`valuePrimitive`](https://www.telerik.com/kendo-angular-ui/components/dropdowns/api/multiselectcomponent#valueprimitive) property is set to `true`, its value will also be of the primitive type (string, number). Use this approach to store only the identifier of each item (for example, a numeric ID) rather than the full object.

The following snippet shows how to store only numeric IDs while the tags still display the human-readable `name`. This pattern is practical when working with server APIs that accept arrays of IDs.

```html app.component.html

<kendo-multiselect
    [data]="categories"
    textField="name"
    valueField="id"
    [valuePrimitive]="true"
    [value]="selectedIds">
</kendo-multiselect>
```

```typescript app.component.ts
public categories = [
    { id: 1, name: 'Electronics' },
    { id: 2, name: 'Clothing' },
    { id: 3, name: 'Books' }
];
public selectedIds: number[] = [1, 3];
```

The following example demonstrates how to bind a MultiSelect to object data while keeping the selected value as an array of primitives.

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

## Invalid Value Errors

If the value which is assigned through the `[value]` or `[(ngModel)]` inputs does not match the expected type, the MultiSelect 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 MultiSelect expects an array of object values. Instead, an array with a number is provided and, as a result, a JavaScript exception occurs.

[Demo Source](https://demos.telerik.com/kendo-angular-ui/demos/dropdowns/multiselect/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]                             |
| :------------ | :--------- | :-------------------------------------------- |
| \[primitives] | primitives | Not set (automatically calculated as `true`)  |
| \[objects]    | objects    | Not set (automatically calculated as `false`) |
| \[primitives] | objects    | `true`  (manually set by the developer)       |

## Suggested Links

* [MultiSelect Data Binding](https://www.telerik.com/kendo-angular-ui/components/dropdowns/multiselect/data-binding)
* [MultiSelect Forms Integration](https://www.telerik.com/kendo-angular-ui/components/dropdowns/multiselect/forms)
* [API Reference of the MultiSelect](https://www.telerik.com/kendo-angular-ui/components/dropdowns/api/multiselectcomponent)
