Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Apr 28, 2025
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions components/multiselect/custom-value.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
title: Custom Value
page_title: MultiSelect - Custom Value
description: Custom values and user input in the MultiColumnComboBox for Blazor.
slug: multiselect-custom-value
tags: telerik,blazor,multiselect,custom,value,input
published: True
position: 16
---

# MultiSelect Custom Values

The MultiSelect component allows the user to type in their own value that is not a part of the predefined set of options that the developer provided.

The text entered by the user can still go into the field the combo box 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 will appear as the first item in the list with the label: `Use"typed value"`. Refer to the example below to see it in action.

> When MultiSelect is bound to a model, 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, and not when an item is selected, because the MultiSelect component acts as 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 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)
1 change: 1 addition & 0 deletions components/multiselect/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-value). 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. |
Expand Down