Getting Started with Dropdown List Component

4 Nov 202511 minutes to read

Overview

The Blazor DropDownList is a dynamic replacement for the HTML select element. It presents a rich UI to select a single, non-editable value from a predefined list. Features include data binding, filtering, grouping, UI customization, accessibility, and preselected values.

This guide explains how to add the Blazor DropDownList component to a Blazor WebAssembly app using Visual Studio, Visual Studio Code, and the .NET CLI. Ensure a valid Syncfusion license is registered in the application and choose a theme (Bootstrap, Fluent, Material, or Tailwind) as part of setup.

To get started quickly with the Blazor DropDownList component, review this GitHub sample.

Prerequisites

Create a new Blazor App in Visual Studio

Create a Blazor WebAssembly App using Visual Studio via Microsoft templates or the Syncfusion® Blazor Extension. For detailed instructions, refer to this guide.

Install Syncfusion® Blazor DropDowns and Themes NuGet in the App

To add the Blazor DropDownList component, open the NuGet Package Manager in Visual Studio (Tools → NuGet Package Manager → Manage NuGet Packages for Solution), then search for and install Syncfusion.Blazor.DropDowns and Syncfusion.Blazor.Themes. Alternatively, use the following Package Manager commands.

Install-Package Syncfusion.Blazor.DropDowns -Version 31.2.12
Install-Package Syncfusion.Blazor.Themes -Version 31.2.12

NOTE

Syncfusion® Blazor components are available on nuget.org. See the NuGet packages page for the complete list of packages and component details.

Prerequisites

Create a new Blazor App in Visual Studio Code

Create a Blazor WebAssembly App using Visual Studio Code via Microsoft templates or the Syncfusion® Blazor Extension. For detailed instructions, refer to this guide.

Alternatively, create a WebAssembly application using the following command in the terminal (Ctrl+`).

dotnet new blazorwasm -o BlazorApp
cd BlazorApp

Install Syncfusion® Blazor DropDowns and Themes NuGet in the App

  • Press Ctrl+` to open the integrated terminal in Visual Studio Code.
  • Ensure the terminal path is the project root directory where the .csproj file is located.
  • Run the following commands to install Syncfusion.Blazor.DropDowns and Syncfusion.Blazor.Themes, and restore dependencies.
dotnet add package Syncfusion.Blazor.DropDowns -v 31.2.12
dotnet add package Syncfusion.Blazor.Themes -v 31.2.12
dotnet restore

NOTE

Syncfusion® Blazor components are available on nuget.org. See the NuGet packages page for the complete list of packages and component details.

Prerequisites

Latest version of the .NET Core SDK. If the SDK is already installed, determine the installed version by running the following command in a command prompt (Windows), terminal (macOS), or command shell (Linux).

dotnet --version

Create a Blazor WebAssembly App using .NET CLI

Run the dotnet new blazorwasm command to create a new Blazor WebAssembly app in a command prompt (Windows), terminal (macOS), or command shell (Linux).

dotnet new blazorwasm -o BlazorApp
cd BlazorApp

This command creates a new Blazor WebAssembly app and places it in a directory named BlazorApp under the current location. See the Create a Blazor app and dotnet new documentation for more details.

Install Syncfusion® Blazor DropDowns and Themes NuGet in the App

Use the following commands to add the Blazor DropDownList component by installing Syncfusion.Blazor.DropDowns and Syncfusion.Blazor.Themes. For more information, see Install and manage packages using the dotnet CLI.

dotnet add package Syncfusion.Blazor.DropDowns -Version 31.2.12
dotnet add package Syncfusion.Blazor.Themes -Version 31.2.12
dotnet restore

NOTE

Syncfusion® Blazor components are available on nuget.org. See the NuGet packages page for the complete list of packages and component details.

Add Import Namespaces

Open the ~/_Imports.razor file and import the Syncfusion.Blazor and Syncfusion.Blazor.DropDowns namespaces.

@using Syncfusion.Blazor
@using Syncfusion.Blazor.DropDowns

Register Syncfusion® Blazor Service

Register the Syncfusion® Blazor service in the ~/Program.cs file of your Blazor WebAssembly app. Ensure a valid Syncfusion license key is registered at application startup before using components.

using Microsoft.AspNetCore.Components.Web;
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Syncfusion.Blazor;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

builder.Services.AddSyncfusionBlazor();
await builder.Build().RunAsync();
....

Add stylesheet and script resources

The theme stylesheet and script are provided via Static Web Assets. Include the stylesheet and script references in the <head> section of the ~/index.html file.

<head>
    ....
    <link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
    <script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js" type="text/javascript"></script>

    //Blazor DropDown List Component script reference.
    <!-- <script src="_content/Syncfusion.Blazor.DropDowns/scripts/sf-dropdownlist.min.js" type="text/javascript"></script> -->
</head>

NOTE

See the Blazor Themes topic for theme reference methods (Static Web Assets, CDN, and CRG). For script references, see Adding Script Reference.

Add Blazor DropDown List component

Add the Syncfusion® Blazor DropDown List component in the ~/Pages/Index.razor file.

<SfDropDownList TValue="string" TItem="string" Placeholder="Select a game"></SfDropDownList>
  • Press Ctrl+F5 (Windows) or ⌘+F5 (macOS) to launch the application. The Syncfusion® Blazor DropDownList component renders in the default web browser.
Blazor DropDownList Component

Binding data source

After initialization, populate the DropDownList with data using the DataSource property.

<SfDropDownList TValue="string" TItem="Games" Placeholder="Select a game" DataSource="@LocalData">
  <DropDownListFieldSettings Value="ID" Text="Text"></DropDownListFieldSettings>
</SfDropDownList>

@code {
  public class Games
  {
    public string ID { get; set; }
    public string Text { get; set; }
  }
  List<Games> LocalData = new List<Games> {
    new Games() { ID= "Game1", Text= "American Football" },
    new Games() { ID= "Game2", Text= "Badminton" },
    new Games() { ID= "Game3", Text= "Basketball" },
    new Games() { ID= "Game4", Text= "Cricket" },
    new Games() { ID= "Game5", Text= "Football" },
    new Games() { ID= "Game6", Text= "Golf" },
    new Games() { ID= "Game7", Text= "Hockey" },
    new Games() { ID= "Game8", Text= "Rugby"},
    new Games() { ID= "Game9", Text= "Snooker" },
    new Games() { ID= "Game10", Text= "Tennis"},
  };
}
Data Binding in Blazor DropDownList

Configure the popup list

By default, the popup list width automatically adjusts to the DropDownList input width, and the popup list height is 350px. Customize the height and width using the PopupHeight and PopupWidth properties.

<SfDropDownList TValue="string" TItem="Games" PopupHeight="350px" PopupWidth="350px" Placeholder="Select a game" DataSource="@LocalData">
  <DropDownListFieldSettings Value="ID" Text="Text"></DropDownListFieldSettings>
</SfDropDownList>

@code{
  public class Games
  {
    public string ID { get; set; }
    public string Text { get; set; }
  }
  List<Games> LocalData = new List<Games> {
    new Games() { ID= "Game1", Text= "American Football" },
    new Games() { ID= "Game2", Text= "Badminton" },
    new Games() { ID= "Game3", Text= "Basketball" },
    new Games() { ID= "Game4", Text= "Cricket" },
    new Games() { ID= "Game5", Text= "Football" },
    new Games() { ID= "Game6", Text= "Golf" },
    new Games() { ID= "Game7", Text= "Hockey" },
    new Games() { ID= "Game8", Text= "Rugby"},
    new Games() { ID= "Game9", Text= "Snooker" },
    new Games() { ID= "Game10", Text= "Tennis"},
  };
}
Changing Popup List Height in Blazor DropDownList

Get selected value

Get the selected value of the DropDownList component in the ValueChange event using the ChangeEventArgs.Value property.

  • CSHTML
    • @using Syncfusion.Blazor.DropDowns

<SfDropDownList TValue="string" TItem="Games" Placeholder="Select a game" DataSource="@LocalData">
  <DropDownListFieldSettings Value="Text" Text="Text"></DropDownListFieldSettings>
  <DropDownListEvents TValue="string" TItem="Games" ValueChange="OnValueChange"></DropDownListEvents>
</SfDropDownList>

@code {
    public class Games
    {  
        public string ID { get; set; }
        public string Text { get; set; }
    }
    List<Games> LocalData = new List<Games> {
    new Games() { ID= "Game1", Text= "American Football" },
    new Games() { ID= "Game2", Text= "Badminton" },
    new Games() { ID= "Game3", Text= "Basketball" },
    new Games() { ID= "Game4", Text= "Cricket" },
    new Games() { ID= "Game5", Text= "Football" },
    new Games() { ID= "Game6", Text= "Golf" },
    new Games() { ID= "Game7", Text= "Hockey" },
    new Games() { ID= "Game8", Text= "Rugby"},
    new Games() { ID= "Game9", Text= "Snooker" },
    new Games() { ID= "Game10", Text= "Tennis"},
  };
    public void OnValueChange(ChangeEventArgs<string, Games> args)
    {
        Console.WriteLine("The DropDownList Value is: ", args.Value);
    }
}

    Get the complete data object for the selected value in the ValueChange event using the ChangeEventArgs.ItemData property.

  • CSHTML
    • @using Syncfusion.Blazor.DropDowns

<SfDropDownList TValue="string" TItem="Games" Placeholder="Select a game" DataSource="@LocalData">
  <DropDownListFieldSettings Value="ID" Text="Text"></DropDownListFieldSettings>
  <DropDownListEvents TValue="string" TItem="Games" ValueChange="OnValueChange"></DropDownListEvents>
</SfDropDownList>

@code {
    public class Games
    {  
        public string ID { get; set; }
        public string Text { get; set; }
    }
    List<Games> LocalData = new List<Games> {
    new Games() { ID= "Game1", Text= "American Football" },
    new Games() { ID= "Game2", Text= "Badminton" },
    new Games() { ID= "Game3", Text= "Basketball" },
    new Games() { ID= "Game4", Text= "Cricket" },
    new Games() { ID= "Game5", Text= "Football" },
    new Games() { ID= "Game6", Text= "Golf" },
    new Games() { ID= "Game7", Text= "Hockey" },
    new Games() { ID= "Game8", Text= "Rugby"},
    new Games() { ID= "Game9", Text= "Snooker" },
    new Games() { ID= "Game10", Text= "Tennis"},
  };
    public void OnValueChange(ChangeEventArgs<string, Games> args)
    {
        Console.WriteLine("The complete data of the selected value is: ", args.ItemData);
    }
}

    See also