Value Binding
The DropDownList value can either be a primitive (strings, numbers, or other) or a complex value (objects).
To set the value, apply any of the following approaches:
- Use the
value
property. If the value is set through thevalue
property, you have to hook up to thevalueChange
event and manually update the value of thevalue
property. - Use the
ngModel
value binding. If the value is set by thengModel
value binding, the framework will automatically update the corresponding field from the model after the value of the component changes. - Use the
formControlName
value binding available in the Reactive forms. If the value is set by theformControlName
value binding, the framework will automatically update the corresponding field from the form model after the value of the component changes.
The DropDownList does not support the simultaneous usage of the
value
property and thengModel
value binding.
When binding the DropDownList value, the component provides options for:
- Using primitive values (strings, numbers, or other)
- Using complex values (objects)
- Using primitive values from object fields
- Handling invalid value errors
Primitive Values
If the DropDownList 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
Object Values
If the DropDownList 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 DropDownList 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 passeddata
object.
Primitive Values from Object Fields
If the DropDownList is bound to a dataset of objects and the valuePrimitive
property is set to true
, the value of the component will be extracted from the valueField
of the objects.
Invalid Value Errors
If the value which is assigned through the [value]
or [(ngModel)]
inputs does not match the expected type, the DropDownList 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 DropDownList expects an object value. Instead, a number is provided and, as a result, a JavaScript exception occurs.
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) |