Components / ComboBox

Blazor ComboBox Overview

The Blazor ComboBox component allows the user to choose an option from a predefined set of choices presented in a dropdown popup. You can also allow them to enter custom values and to filter the available items. You can control the data, sizes, and various appearance options like class and templates.

Telerik UI for Blazor Ninja image

The ComboBox component is part of Telerik UI for Blazor, a professional grade UI library with 100+ native components for building modern and feature-rich applications. To try it out sign up for a free 30-day trial.

Download Free Trial

Creating ComboBox

  1. Use the TelerikComboBox tag to add the component to your razor page.
  2. Populate the Data property with the collection of items that you want to appear in the dropdown.
  3. Set the TextField and ValueField properties to point to the corresponding names of the model
  4. Bind the value of the component to a variable of the same type as the type defined in the ValueField parameter.
  5. (optional) enable features like filtering and clear button

Combobox data binding with two-way value binding

Selected value: @selectedValue
<br />

<TelerikComboBox Data="@myComboData" TextField="MyTextField" ValueField="MyValueField" @bind-Value="selectedValue"
                 Placeholder="Select an item..." ClearButton="true" Filterable="true">
</TelerikComboBox>

@code {
    IEnumerable<MyDdlModel> myComboData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });

    int selectedValue { get; set; }    

    //in a real case, the model is usually in a separate file
    //the model type and value field type must be provided to the dropdpownlist
    public class MyDdlModel
    {
        public int MyValueField { get; set; }
        public string MyTextField { get; set; }
    }
}

Data Binding

The Blazor ComboBox requires a data source so that it can populate the dropdown with data. To provide a data source, use the Data property. Read more about the Blazor ComboBox data binding....

Filtering

The Blazor ComboBox has a built-in filter that narrows down the shown suggestions as the end-user types. To configure this feature, use the Filterable parameter. Additionally, you can choose between different filter operators and configure after how many symbols the list with suggestions will appear. Read more about the Blazor ComboBox filter....

Grouping

The Blazor ComboBox enables you to group the listed suggestions into categories so you can help the end-user to browse faster through longer lists. Read more about the Blazor ComboBox grouping....

Templates

You can use the functionality of the built-in templates and customize the default rendering of the component. Read more about the Blazor ComboBox templates....

Validation

You can ensure that the component value is acceptable by using the built-in validation. Read more about input validation....

Virtualization

By virtualizing the elements in the dropdown, you can use huge data sources without performance issues. The UI virtualization works with both local and remote data. Read more about the Blazor ComboBox virtualization...

Adaptive Rendering

The component supports different popup rendering depending on the screen size. Read more about the Adaptive Rendering functionality and how to enable it...

Parameters

The ComboBox provides various parameters that allow you to configure the component:

Parameter Type Description
AdaptiveMode AdaptiveMode
(None)		 The adaptive mode of the component.
AllowCustom bool whether the user can enter custom values. If enabled, the ValueField must be a string.
ClearButton bool whether the user will have the option to clear the selected value. When it is clicked, the Value will be updated to default(TValue), so there must be no item in the Data that has such a Value. For example, if TValue is int, clearing the value will lead to a 0 Value, so if there is an Item with 0 in its ValueField - issues may arise with its selection. This feature can often go together with AllowCustom.
Data IEnumerable<TItem> allows you to provide the data source. Required.
DebounceDelay int
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.
Enabled bool whether the component is enabled.
Filterable bool whether filtering is enabled for the end user.
FilterOperator StringFilterOperator
(StartsWith)		 the method of filtering the items.
Id string renders as the id attribute on the <input /> element, so you can attach a <label for=""> to the input.
Placeholder string the text the user sees as a hint when no item is selected. In order for it to be shown, the Value parameter should be set to a default value depending on the type defined in the ValueField parameter. For example, 0 for an int, and null for an int? or string. You need to make sure that it does not match the value of an existing item in the data source.
TItem Type the type of the model to which the component is bound. Required if you can't provide Data or Value. Determines the type of the reference object.
TValue Type the type of the value field from the model to which the component is bound. Required if you can't provide Data or Value. Determines the type of the reference object. The type of the values can be:
- number (such as int, double, and so on)
- string
- Guid
- Enum
Title string The title text rendered in the header of the popup(action sheet). Applicable only when AdaptiveMode is set to Auto.
TextField string
(Text)		 the name of the field from the model that will be shown to the user.
ValueField string
(Value)		 the name of the field from the model that will be the underlying value.
Value and bind-Value TValue get/set the value of the component, can be used for binding. If you set it to a value allowed by the model class value field, the corresponding item from the data collection will be pre-selected. Use the bind-Value syntax for two-way binding, for example, to a variable of your own.
TabIndex int? maps to the tabindex attribute of the HTML element. You can use it to customize the order in which the inputs in your form focus with the Tab key.

Styling and Appearance

The following parameters enable you to customize the appearance of the Blazor ComboBox:

Parameter Type Description
Class string The CSS class that will be rendered on the main wrapping element of the component. Use it to override the theme or apply custom styles.
Width string The width of the component. It will target both the dropdown and the main element if the dropdown has no specific width set. The default Width value is null, but the theme applies 100%. Use the Width property or custom CSS to set another value in any supported unit.

You can find more options for customizing the ComboBox styling in the Appearance article.

The popup of the component can be additionally customized via nested tags:

<div class="skip-repl"></div>
<TelerikComboBox>
    <ComboBoxSettings>
        <ComboBoxPopupSettings Height="..." />
    </ComboBoxSettings>
</TelerikComboBox>

The ComboBox provides the following popup settings:

Parameter Type Description
AnimationDuration int The animation duration of the popup in milliseconds.
Class string Additional CSS class to customize the appearance of the popup.
Height string The height of the popup.
MinHeight string The minimum height of the popup.
MinWidth string The minimum width of the popup.
MaxHeight string The maximum height of the popup.
MaxWidth string The maximum width of the popup.
Width string The width of the popup. If you don't specify a value, the dropdown width will match the anchor element width which can help with responsive layouts and 100% widths.

ComboBox Reference and Methods

The ComboBox is a generic component and its type is determined by the type of the model you pass to it, and the type of its value field. You can find examples in the Data Bind - Considerations article.

Add a reference to the component instance to use the ComboBox's methods.

Method Description
Close Closes the popup.
FocusAsync Focuses the main element of the component. Always await this call, as it relies on JSInterop.
Open Opens the popup. 
<TelerikComboBox @ref="@ComboBoxRef"
                     Data="@Suggestions"
                     @bind-Value="@ComboBoxValue" 
                     Width="300px"/>

<TelerikButton OnClick="@OpenPopup">Open Popup</TelerikButton>

@code {
    private TelerikComboBox<string, string> ComboBoxRef { get; set; }

    private string ComboBoxValue { get; set; }

    private List<string> Suggestions { get; set; } = new List<string> { "first", "second", "third" };

    private void OpenPopup()
    {
        ComboBoxRef.Open();
    }
}

Selected Item

By default, if no Value is provided, the ComboBox will appear empty, or will display the Placeholder defined. If a Value is provided and AllowCustom is not set to true, the Value should match an item in the data source (see more in the Value Out of Range section).

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 user clears the value through the Clear button,
  • the user clears the value with Backspace or Del keys,
  • AllowCustom="false" - when a custom value is typed, the ComboBox input value will be automatically cleared on the change event (blur of the input or Enter keypress). See the table below.
  • AllowCustom="true" - when the user starts typing a custom value.

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 AllowCustom=true AllowCustom=false
The TextField of an item Matched item is selected. The Value is taken from the item. Matched item is selected. The Value is taken from the item.
The ValueField of an item No item is selected. Value is updated to the custom one. No item is selected. Value is updated to default(typeof(Value)). The OnChange event does not fire for the value clearing.
No match No item is selected. Value is updated to the custom one. No item is selected. Value is updated to default(typeof(Value)). The OnChange event does not fire for the value clearing.

If you are looking for more fields from the view-model that describes the dropdown items, not just the Value, see the Get model from dropdown KB article and the OnChange event.

You may also want to review/join the discussion and Vote for this request: Binding DropDownList Value to complex model

Next Steps

See Also

In this article
Related articles
Not finding the help you need? Improve this article