docs(MultiSelect): add docs for custom values (#2917)

* docs(MultiSelect): add docs for custom values

* chore(MultiSelect): polish article

* Update components/multiselect/custom-value.md

Co-authored-by: Nadezhda Tacheva <73842592+ntacheva@users.noreply.github.com>

* Update components/multiselect/overview.md

Co-authored-by: Nadezhda Tacheva <73842592+ntacheva@users.noreply.github.com>

---------

Co-authored-by: Nadezhda Tacheva <73842592+ntacheva@users.noreply.github.com>

Author: Tsvetomir-Hr

components/multiselect/custom-value.md

@@ -0,0 +1,67 @@
+---
+title: Custom Values
+page_title: MultiSelect - Custom Values
+description: Learn how to use custom values and user input in the MultiSelect for Blazor.
+slug: multiselect-custom-values
+tags: telerik,blazor,multiselect,custom,value,input
+published: True
+position: 16
+---
+
+# MultiSelect Custom Values
+
+The MultiSelect component lets users type their own values that are not part of the options predefined by the developer.
+
+The text entered by the user can still go into the collection that MultiSelect component is bound to through two-way binding.
+
+To enable custom user input, set the `AllowCustom` parameter to `true`. When the user types a custom value, it appears as the first item in the list with the label: `Use "typed value"`. The user must select (click) the value, to actually add it the collection of values that MultiSelect is bound to. Refer to the example below to see the feature in action.
+
+> When custom values are enabled, the `TextField`, `ValueField` and the `Value` must be of type `string`. Otherwise an exception will be thrown. Strings are required because the user input can take any form and may not be parsable to other types (such as numbers or GUID).
+
+When custom input is allowed, the [`ValueChanged` event](slug:multiselect-events#valuechanged) fires on every keystroke, instead of when an item is selected. This happens because the MultiSelect component behaves like a text input.
+
+>caption Allow custom user input in the MultiSelect component
+
+````RAZOR
+<TelerikMultiSelect Data="@Cities"
+                    @bind-Value="@SelectedCities"
+                    TextField="@nameof(City.CityName)" 
+                    ValueField="@nameof(City.CityName)"
+                    AllowCustom="true"
+                    Placeholder="Select a city for the list or type a custom one"
+                    Width="400px">
+</TelerikMultiSelect>
+
+@code {
+    private List<City> Cities { get; set; } = new();
+    private List<string> SelectedCities { get; set; } = new();
+
+    protected override void OnInitialized()
+    {
+        Cities = new List<City>
+        {
+            new City { CityId = 1, CityName = "New York"},
+            new City { CityId = 2, CityName = "London"},
+            new City { CityId = 3, CityName = "Tokyo"},
+            new City { CityId = 4, CityName = "Paris"},
+            new City { CityId = 5, CityName = "Sydney"}
+        };
+
+        base.OnInitialized();
+    }
+
+    public class City
+    {
+        public int CityId { get; set; }
+        public string CityName { get; set; } = string.Empty;
+    }
+}
+````
+
+## Limitations
+
+* `AllowCustom` is not compatible with [adaptive rendering](slug:adaptive-rendering).
+
+## See Also
+
+* [MultiSelect Overview](slug:multiselect-overview)

components/multiselect/overview.md

@@ -99,6 +99,7 @@ The Blazor MultiSelect provides various parameters that allow you to configure t
 | ----------- | ----------- | ------ |
 | `AdaptiveMode` | `AdaptiveMode` <br /> (`None`) | The [adaptive mode](slug:adaptive-rendering) of the component. |
 | `AutoClose` | `bool` <br /> (`true`) | Defines whether the dropdown list containing the items for the MultiSelect will automatically close after each user selection. |
+| `AllowCustom` | `bool` | Determines if the user can enter [custom values](slug:multiselect-custom-values). If enabled, the `ValueField` must be a `string`. |
 | `ShowClearButton` | `bool` | Whether the user will have the option to clear the selected items with a button on the input. When it is clicked, the `Value` will be updated to an empty list. |
 | `Data` | `IEnumerable<TItem>` | Allows you to provide the data source. Required. |
 | `DebounceDelay` | `int` <br/> 150 | Time in milliseconds between the last typed symbol and the internal `oninput` event firing. Applies when the user types and filters. Use it to balance between client-side performance and number of database queries. |