Components / DropDownList

DropDownList Overview

The 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.

To use a Telerik DropDownList for Blazor

  1. add the TelerikDropDownList tag
  2. populate its Data property with the collection of items you want in the dropdown
  3. set the TextField and ValueField properties to point to the corresponding names of the model
  4. set the Value property to the intial value of the model.

Basic dropdownlist data binding and ValueChanged event handling

.NET Core Issue 8385 is preventing the ValueChanged handler from working at the moment. The code below will work as soon as Microsoft release a fix for this problem. Until then, you may get compilation issue due to the handler presence. We strive to follow best practices and future-proof our components, which is why we are using this approach even though it does not work yet.

@using Telerik.Blazor.Components.DropDownList

<TelerikDropDownList Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" ValueChanged="@MyValueChangedHandler" @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; }
    }

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

    int selectedValue { get; set; } = 3; //usually the current value should come from the model data

    void MyValueChangedHandler(object newValue)
    {
        //the data item (model) that the user selected
        Console.WriteLine((newValue as MyDdlModel).MyTextField);
    }
}

The result from the code snippet above

Component namespace and reference

@using Telerik.Blazor.Components.DropDownList

<TelerikDropDownList @ref="myDdlRef" Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" Value="3">
</TelerikDropDownList>
@code {
    //the type of the generic component is determined by the type of the model you pass to it, and the type of its value field
    Telerik.Blazor.Components.DropDownList.TelerikDropDownList<MyDdlModel, int> myDdlRef;

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

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

The DropDownList provides the following features:

  • Class - the CSS class that will be rendered on the main wrapping element of the dropdownlist.
  • Data - allows you to provide the data source. Required.
  • DefaultItem - sets the hint that is shown if no other item is selected. Set this property to an instance of the model class to which the dropdown is bound.
  • Enabled - whether the component is enabled.
  • Height - the height of the main element. See the Dimensions article.
  • PopupHeight - the height of the expanded dropdown list element.
  • T - the type of the model to which the component is bound. Required. Determines the type of the reference object.
  • TItem - the type of the value field from the model to which the component is bound. Required. Determines the type of the reference object.
  • TabIndex - the tabindex attribute rendered on the dropdown.
  • TextField - the name of the field from the model that will be shown to the user. Defaults to Text.
  • ValueField - the name of the field from the model that will be the underlying value. Defaults to Value.

  • Value and bind-Value- 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.

    The Value and ValueField can be of types:

    • number (such as int, double and so on)
    • string
    • Guid
    • Enum

  • Width - the width of the dropdown and the main element.

  • Templates - they allow you to control the rendering of items in the component. See the Templates article for more details.
  • Validation - see the Input Validation article for more details.

Examples

Validating a dropdownlist. See the comments in the code for details on the behavior

@using Telerik.Blazor.Components.DropDownList
@using System.ComponentModel.DataAnnotations

<EditForm Model="@person" OnValidSubmit="@HandleValidSubmit">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <p class="gender">
        Gender: <TelerikDropDownList @bind-Value="person.Gender" DefaultItem="@ddlHint"
                                   Data="@genders" TextField="MyTextField" ValueField="MyValueField">
                </TelerikDropDownList>
        <ValidationMessage For="@(() => person.Gender)"></ValidationMessage>
    </p>

    <button type="submit">Submit</button>
</EditForm>

@code {
    // Usually the model classes would be in different files
    public class Person
    {
        [Required(ErrorMessage = "Gender is mandatory.")]//the value field in the dropdown model must be null in the default item
        [Range(1, 3, ErrorMessage = "Please select your gender.")] //limits the fourth option just to showcase this is honored
        public int? Gender { get; set; }
    }

    public class MyDdlModel
    {
        //nullable so the default item can allow required field validation
        //alternatively, use a range validator and put a value out of that range for the default item
        public int? MyValueField { get; set; }
        public string MyTextField { get; set; }
    }

    Person person = new Person();

    MyDdlModel ddlHint = new MyDdlModel { MyValueField = null, MyTextField = "Gender" };

    IEnumerable<MyDdlModel> genders = new List<MyDdlModel>
{
        new MyDdlModel {MyTextField = "female", MyValueField = 1},
        new MyDdlModel {MyTextField = "male", MyValueField = 2},
        new MyDdlModel {MyTextField = "other", MyValueField = 3},
        new MyDdlModel {MyTextField = "I'd rather not say", MyValueField = 4}
    };

    void HandleValidSubmit()
    {
        Console.WriteLine("OnValidSubmit");
    }
}

Get selected item from external code

@using Telerik.Blazor.Components.DropDownList
@using Telerik.Blazor.Components.Button

<TelerikDropDownList @ref="myDdlRef" Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" Value="5">
</TelerikDropDownList>
<TelerikButton OnClick="@GetSelectedItem">Get Selected Item</TelerikButton> @result
@code {
    string result;
    void GetSelectedItem()
    {
        if (myDdlRef.SelectedDataItem != null)
        {
            result = (myDdlRef.SelectedDataItem as MyDdlModel).MyTextField;
        }
        else
        {
            result = "no item selected";
        }

        StateHasChanged();
    }

    //the type of the generic component is determined by the type of the model you pass to it, and the type of its value field
    Telerik.Blazor.Components.DropDownList.TelerikDropDownList<MyDdlModel, int> myDdlRef;

    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 });
}

See Also

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