Blazor DropDownList Overview
The Blazor DropDownList component allows the user to choose an option from a predefined set of choices presented in a dropdown list 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 110+ native components for building modern and feature-rich applications. To try it out sign up for a free 30-day trial.
Creating the 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 list. - Set the
TextField
andValueField
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) Set the
Value
property to the initial value of the model.
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; } = 3;
IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
}
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....
Grouping
The Blazor DropDownList 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 DropDownList 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 DropDownList 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 DropDownList 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
Parameter | Type | Description |
---|---|---|
AdaptiveMode |
AdaptiveMode ( None ) |
The adaptive mode of the component. |
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. |
ReadOnly |
bool |
If set to true , the component will be readonly and will not allow user input. The component is not readonly by default and allows user input. |
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. |
FilterPlaceholder |
string |
The hint that will be displayed in the filter input when it has no value. |
Id |
string |
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
|
Title |
string |
The title text rendered in the header of the dropdown list popup (action sheet). Applicable only when AdaptiveMode is set to Auto . |
TabIndex |
int? |
The tabindex attribute rendered on the dropdown list. |
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 |
Gets/sets 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 component:
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. |
To learn more about the appearance, anatomy, and accessibility of the DropDownList, visit the Progress Design System Kit documentation—an information portal offering rich component usage guidelines, descriptions of the available style variables, and globalization support details.
Popup Settings
The DropDownList exposes settings for its dropdown (popup). To configure the options, declare a <DropDownListPopupSettings>
tag inside a <DropDownListSettings>
tag:
<TelerikDropDownList Data="@DropDownData"
@bind-Value="@SelectedItem"
Filterable="true"
FilterOperator="@StringFilterOperator.Contains"
FilterPlaceholder="Filter by digit or letter"
Width="240px">
<DropDownListSettings>
<DropDownListPopupSettings Height="auto" MaxHeight="200px" MinHeight="75px" />
</DropDownListSettings>
</TelerikDropDownList>
@code {
private List<string> DropDownData { get; set; } = Enumerable.Range(1, 50)
.Select(x => { return $"Item {x} {(char)Random.Shared.Next(65, 91)}{(char)Random.Shared.Next(65, 91)}"; })
.ToList();
private string SelectedItem { get; set; }
}
The DropDownList provides the following popup settings:
Parameter | Type | Description |
---|---|---|
AnimationDuration |
int ( 300 ) |
The dropdown animation duration in milliseconds. |
Class |
string |
Additional CSS class to customize the appearance of the popup. |
Height |
string ( "200px" ) |
The height of the popup. If set to "auto" , the component will automatically adjust the popup height based on the number of items and available space. Setting MaxHeight disables the built-in screen boundary detection. This means that the component will no longer adjust the dropdown height to fit within the viewport. |
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. |
The parameters that modify the popup dimensions (Height
, Width
, MaxWidth
, etc.) expect valid CSS values.
The MinHeight
and MaxHeight
have no effect if the Height
is always within their range. The min and max values are useful only when the dropdown height is set to a relative unit or changes at runtime.
If the Virtualization feature is enabled, it's important to note that the auto popup width functionality doesn't work as expected. In this scenario, the dropdown popup width does not dynamically adjust based on the data items. When dealing with virtualization and long items, specifying a fixed popup
Width
becomes imperative. For example, set a fixed width like"300px"
. To determine this fixed width value, you can identify the longest item in the dropdown collection and calculate the required pixel width based on it.
DropDownList Reference and Methods
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.
Add a reference to the component instance to use the DropDownList'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 . Also check the dedicated KB article about programmatic input component focusing, which provides more examples and tips. |
Open |
Opens the popup. |
Refresh |
Re-renders the component popup. |
<TelerikDropDownList @ref="@DropDownListRef"
Data="@DropDownListData"
@bind-Value="@DropDownListValue"
Width="300px" />
<TelerikButton OnClick="@OpenPopup">Open Popup</TelerikButton>
@code {
private TelerikDropDownList<string, string> DropDownListRef { get; set; }
private string DropDownListValue { get; set; }
private List<string> DropDownListData { get; set; } = new List<string> { "first", "second", "third" };
private void OpenPopup()
{
DropDownListRef.Open();
DropDownListValue = DropDownListData.First();
DropDownListRef.Refresh();
}
}
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 be0
ornull
depending on the data type you are using in theValueField
and theDefaultText
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
@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; }
}
@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