docs(combobox): info for onchange and selected items

Author: marin-bratanov

components/combobox/events.md

@@ -13,7 +13,7 @@ position: 20
 This article explains the events available in the Telerik ComboBox for Blazor:
 
 * [ValueChanged](#valuechanged)
-* `OnChange` - inherited event that you should not use, but you may see in the intellisense
+* [OnChange](#onchange)
 
 
 ## ValueChanged
@@ -94,6 +94,81 @@ from model: @MyItem
 }
 ````
 
+
+## OnChange
+
+The `OnChange` event is suitable for handling custom values the user can enter as if the combo box were an input. The key differences with `ValueChanged` are:
+
+* `OnChange` does not prevent two-way binding (the `@bind-Value` syntax)
+* `OnChange` fires only when the user presses `Enter`, or blurs the input (for example, clicks outside of the combo box). It does not fire on every keystroke, even when `AllowCustom="true"`, and it does not fire when an item is selected from the dropdown.
+
+See the [ComboBox Overview - Selected Item]({%slug components/combobox/overview%}#selected-item) article for details on when the event fires and how item selection works.
+
+>caption Handle OnChange without custom values - you must write text that will match an item.
+
+````CSHTML
+@result
+<br />
+@selectedValue
+<br /><br />
+<TelerikComboBox Data="@myComboData" TextField="MyTextField" ValueField="MyValueField"
+                 @bind-Value="@selectedValue" OnChange="@MyOnChangeHandler">
+</TelerikComboBox>
+
+@code {
+    string result;
+    int selectedValue { get; set; } = 3;
+
+    private void MyOnChangeHandler(object theUserInput)
+    {
+        // the handler receives an object that you may need to cast to the type of the component
+        // if you do not provide a Value, you must provide the Type parameter to the component
+        result = string.Format("The user entered: {0}", (int)theUserInput);
+    }
+
+    public class MyComboModel
+    {
+        public int MyValueField { get; set; }
+        public string MyTextField { get; set; }
+    }
+
+    IEnumerable<MyComboModel> myComboData = Enumerable.Range(1, 20).Select(x => new MyComboModel { MyTextField = "item " + x, MyValueField = x });
+}
+````
+
+>caption Handle OnChange with custom values - the event fires on blur or enter
+
+````CSHTML
+@result
+<br />
+@selectedValue
+<br /><br />
+<TelerikComboBox Data="@myComboData" TextField="MyTextField" ValueField="MyValueField"
+                 @bind-Value="@selectedValue" OnChange="@MyOnChangeHandler" AllowCustom="true">
+</TelerikComboBox>
+
+@code {
+    string result;
+    string selectedValue { get; set; } = "3";
+
+    private void MyOnChangeHandler(object theUserInput)
+    {
+        // the handler receives an object that you may need to cast to the type of the component
+        // if you do not provide a Value, you must provide the Type parameter to the component
+        result = string.Format("The user entered: {0}", (string)theUserInput);
+    }
+
+    public class MyComboModel
+    {
+        public string MyValueField { get; set; }
+        public string MyTextField { get; set; }
+    }
+
+    IEnumerable<MyComboModel> myComboData = Enumerable.Range(1, 20).Select(x => new MyComboModel { MyTextField = "item " + x, MyValueField = x.ToString() });
+}
+````
+
+
 ## See Also
 
 * [ValueChanged and Validation]({%slug value-changed-validation-model%})

components/combobox/overview.md

@@ -80,7 +80,27 @@ The ComboBox is a generic component and its type is determined by the type of th
 * Validation - see the [Input Validation]({%slug common-features/input-validation%}) article for more details.
 
 
->note If the initial `Value` is not present in the data source, the component will **not** select the first item of the data source - there will simply be no selection. For such cases you may want to set `AllowCustom="true"`. This scenario is most common when the initial value is `null` as data sources rarely have items with a `null` value, and when you want to let your users type in values that are not in your predefined set of options.
+## Selected Item
+
+By default, if no `Value` is provided, the first item from the data source will be selected. If a `Value` is provided, the first item from the data source whose `ValueField` matches will be selected.
+
+The ComboBox will not always have a selected item, however, because it can act as an input. There will be no selected item in the following cases that depend on the settings of the component that the developer can control:
+
+* the initial `Value` is not present in the data source,
+* the user clears the value through the Clear button,
+* `AllowCustom="true"` - only initial selection is possible, through the `Value` parameter and user actions remove it (see the table below).
+
+
+Missing selection is most common when the initial value is `null` as data sources rarely have items with a `null` value, and/or when you want to let your users type in values that are not in your predefined set of options.
+
+If the user types text in the input, selection behaves according to the following table:
+
+
+| User input matches an item | AllowCustom=`true`   | AllowCustom=`false`                      |
+|----------------------------|----------------------|------------------------------------------|
+| Yes                        | No item is selected. | Matching item is selected.               |
+| No                         | No item is selected. | If there was no previous selection, no item is selected. If there was previous selection, the previously selected item is selected. The `OnChange` event does not fire. |
+
 
 
 ## See Also