Blazor DropDownList Overview

The Blazor DropDownList component allows the user to choose an option from a predefined set of choices presented in a dropdown popup. The developer can control the data, sizes, and various appearance options like class and templates.

The DropDownList component is part of Telerik UI for Blazor, a professional grade UI library with 95+ 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 DropDownList

Use the TelerikDropDownList tag to add the component to your razor page.
Populate its Data property with the collection of items you want to appear in the dropdown.
set the TextField and ValueField properties to point to the corresponding names of the model
Bind the value of the component to a variable of the same type as the type defined in the ValueField parameter.
(optional) enable features like filtering and clear button
(optional) set the Value property to the initial value of the model.

DropDownList data binding, two-way value binding and main features

Selected value: @selectedValue
<br />

<TelerikDropDownList Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" @bind-Value="selectedValue">
</TelerikDropDownList>

@code {
    //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; }
    }

    int selectedValue { get; set; }

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

Component Reference

The DropDownList is a generic component and its type comes from the model it is bound to and from the value field type. See the Component Reference section in the Data Binding article for details and examples.

Data Binding

The Blazor DropDownList 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 DropDownList data binding....

Filtering

The Blazor DropDownList 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 DropDownList filter....

Parameter	Type	Description
`Data`	`IEnumerable<TItem>`	allows you to provide the data source. Required.
`DefaultText`	`string`	simple hint to be displayed when no item is selected yet. 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. See the first example in the Examples section in this article and in the Input Validation article.
`Enabled`	`bool`	whether the component is enabled.
`Filterable`	`bool`	whether filtering is enabled for the end user.
`FilterDebounceDelay`	`int` 150	Time in milliseconds between the last typed symbol and the filter input value update. Applicable to filtering only. Use it to balance between client-side performance and number of database queries.
`FilterOperator`	`StringFilterOperator` (`StartsWith`)	the method of filtering the items.
`Id`	`string`	renders as the `id` attribute on the `<select />` element, so you can attach a `<label for="">` to it.
`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`
`TabIndex`	`int?`	the `tabindex` attribute rendered on the dropdown.
`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.

Styling and Appearance

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

Parameter	Type	Description
`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.
`Class`	`string`	the CSS class that will be rendered on the main wrapping element of the component.

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

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

<TelerikDropDownList>
    <DropDownListSettings>
        <DropDownListPopupSettings Height="..." />
    </DropDownListSettings>
</TelerikDropDownList>

The DropDownList provides the following popup settings:

Parameter	Type	Description
`AnimationDuration`	`int`	the animation duration of the popup.
`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.
`MaxHeight`	`string`	the maximum height 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.
`MinWidth`	`string`	the minimum width of the popup.
`MaxWidth`	`string`	the maximum width of the popup.

Selected Item and DefaultText

By default, if no Value is provided and no DefaultText is defined, the DropDownList will appear empty.

To display DefaultText - Value should be 0 or null depending on the data type you are using in the ValueField and the DefaultText should be defined.
To display a selected item when the component renders - provide the Value of the desired element. Note that it must match an item of the component's data source.

Examples

Default text (hint) to show when no actual item is selected

@MyStringItem
<TelerikDropDownList Data="@MyStringList" @bind-Value="@MyStringItem" DefaultText="Select something">
</TelerikDropDownList>

<br />
<br />

@MyIntItem
<TelerikDropDownList Data="@MyIntList" @bind-Value="@MyIntItem" DefaultText="Select another thing">
</TelerikDropDownList>

@code {
    protected List<string> MyStringList = new List<string>() { "first", "second", "third" };

    //Current value is null (no item is sellected) which allows the DefaultText to be displayed.
    protected string MyStringItem { get; set; }

    protected List<int> MyIntList = new List<int>() { 1, 2, 3 };

    //Current value is 0 (no item is sellected) which allows the DefaultText to be displayed.
    protected int MyIntItem { get; set; }
}

Get selected item from external code

@result
<br />

<TelerikDropDownList Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField"
                     @bind-Value="@DdlValue" DefaultText="Select something">
</TelerikDropDownList>

<TelerikButton OnClick="@GetSelectedItem">Get Selected Item</TelerikButton>

@code {
    string result;
    int DdlValue { get; set; } = 5;
    void GetSelectedItem()
    {
        // extract the data item from the data source by using the value
        MyDdlModel selectedItem = myDdlData.Where(d => d.MyValueField == DdlValue).FirstOrDefault();
        if (selectedItem != null)
        {
            result = selectedItem.MyTextField;
        }
        else
        {
            result = "no item selected";
        }

        StateHasChanged();
    }

    public class MyDdlModel
    {
        public int MyValueField { get; set; }
        public string MyTextField { get; set; }
    }

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

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

Blazor DropDownList Overview

Creating DropDownList

Component Reference

Data Binding

Filtering

Grouping

Templates

Validation

Virtualization

Parameters

Styling and Appearance

Selected Item and DefaultText

Examples

Next Steps

See Also

Getting Started

Community

Support Resources

Sample Applications