DxComboBox<TData, TValue> Class

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.dll

Declaration

public class DxComboBox<TData, TValue> :
    DxDropDownBase<TData, ComboBoxJSInteropProxy>,
    IDataSourceSettings<TData>,
    IInputBase,
    IServiceProviderAccessor,
    IRequireSelfCascading,
    IDropDownWidthModeAccessor,
    IComboBoxJSInteropProxyServer,
    IDisposable

Type Parameters

Remarks

The DevExpress ComboBox for Blazor (<DxComboBox>) component displays a drop-down window with a list of items.

Add ComboBox to a Project

To add the <DxComboBox> component to an application, follow the steps below:

1. Create an application. If you use Microsoft project templates, configure the application as described in this topic: Use Microsoft Templates.
2. Add the <DxComboBox>...</DxComboBox> markup to your application.
3. Bind the component to a data source (see details below).
4. Configure the component (see the sections below).

Bind to Data

Use the Data property to bind the ComboBox to an IEnumerable<T> data source synchronously. If the data source is large or requires access to a remote web service over slow networks, use the DataAsync property instead. It allows you to load data asynchronously and await completion without blocking application code execution.

<DxComboBox Data="@Cities"></DxComboBox>

@code {
  IEnumerable<string> Cities = new List<string>() {
    "London",
    "Berlin",
    "Paris",
  };
}

If you bind the ComboBox to a data source that stores custom objects (IEnumerable<CustomType>), use the TextFieldName property. It specifies the custom object's field name that returns string values to be shown within the ComboBox's drop-down window.

@using BlazorApp.Data

<DxComboBox Data="@Persons.DataSource"
            TextFieldName="Text">
</DxComboBox>

namespace BlazorApp.Data {
    public class Person {
        public int Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public Department Department { get; set; }
        public string Text => $"{FirstName} {LastName} ({Department} Dept.)";
    }

    public enum Department { Motors, Electronics, Software }
}

using System;
using System.Collections.Generic;

namespace BlazorApp.Data {
    public static class Persons {
        private static readonly Lazy<List<Person>> dataSource = new Lazy<List<Person>>(() => {
            var dataSource = new List<Person>() {
                new Person() { Id= 0 , FirstName="John", LastName="Heart", Department=Department.Electronics },
                new Person() { Id= 1 , FirstName="Samantha", LastName="Bright", Department=Department.Motors },
                new Person() { Id= 2 , FirstName="Arthur", LastName="Miller", Department=Department.Software },
                new Person() { Id= 3 , FirstName="Robert", LastName="Reagan", Department=Department.Electronics },
                new Person() { Id= 4 , FirstName="Greta", LastName="Sims", Department=Department.Motors },
                new Person() { Id= 5 , FirstName="Brett", LastName="Wade", Department=Department.Software },
                new Person() { Id= 6 , FirstName="Sandra", LastName="Johnson", Department=Department.Electronics },
                new Person() { Id= 7 , FirstName="Edward", LastName="Holmes", Department=Department.Motors },
                new Person() { Id= 8 , FirstName="Barbara", LastName="Banks", Department=Department.Software },
                new Person() { Id= 9 , FirstName="Kevin", LastName="Carter", Department=Department.Electronics },
                new Person() { Id= 10, FirstName="Cynthia", LastName="Stanwick", Department=Department.Motors },
                new Person() { Id= 11, FirstName="Sam", LastName="Hill", Department=Department.Electronics },
            return dataSource;
        });
        public static List<Person> DataSource { get { return dataSource.Value; } }
    }
}

Otherwise, the ComboBox items are populated with CustomType.ToString() values.

To bind the ComboBox to a data source that is not of the IEnumerable<T> type, assign the data source type to the component's T parameter and use the CustomData property to implement the data load logic.

Items

The <DxComboBox> drop-down window displays a list of predefined items. Set the AllowUserInput property to true to allow users to type values into the ComboBox's edit box.

<DxComboBox Data="@Cities"
            AllowUserInput="true"
            NullText="Select City ..."
            @bind-Value="@Value"
            @bind-Text="@Text">
</DxComboBox>

@code {
  IEnumerable<string> Cities = new List<string>() {
    "London",
    "Berlin",
    "Paris",
  };

  string Text { get; set; } = "New York";
  string Value { get; set; }
}

To specify an editor value in code, use the Text property. To respond to an editor's text change, handle the TextChanged event.

The table below lists API members related to ComboBox item collection:

Null Value

Set the ClearButtonDisplayMode property to Auto to show the Clear button when the editor has a non-null value. Users can click this button to clear the editor's value (set it to null).

Use the NullText property to display the prompt text in the editor when its value is null.

<DxComboBox Data="@DataSource"
            ClearButtonDisplayMode="DataEditorClearButtonDisplayMode.Auto"
            NullText="Select an option..."
            ...>
</DxComboBox>

@code {
    List<Options> DataSource = ...

    Options SelectedOption { get; set; }
}

Cascading Comboboxes

The <DxComboBox> allows you to create cascade lists - populate one ComboBox with items based on the user selection from another ComboBox. Use the Value property to access the selected item. To respond to the selected item change, handle the ValueChanged event.

<DxComboBox Data="@Countries"
            TextFieldName="@nameof(Country.CountryName)"
            Value="@CurrentCountry"
            ValueChanged="@((Country country) => SelectedCountryChanged(country))">
</DxComboBox>

<DxComboBox Data="@CurrentCountryCities"
            TextFieldName="@nameof(City.CityName)"
            @bind-Value="@CurrentCity">
</DxComboBox>

@code {
    List<Country> Countries { get; set; } = CountryCity.Countries;
    List<City> CurrentCountryCities { get; set; } = new List<City>();
    Country CurrentCountry { get; set; } = CountryCity.Countries[1];
    City CurrentCity { get; set; } = CountryCity.Cities[4];

    void SelectedCountryChanged(Country country) {
        CurrentCountry = country;
        CurrentCountryCities = Cities.FindAll(city => city.CountryId == CurrentCountry.Id);
        CurrentCity = CurrentCountryCities[0];
    }
}

Filter Data

<DxComboBox> allows you to dynamically filter list items based on the text typed into the editor. Use the FilteringMode property to enable filtering and specify the filter mode (Contains or StartsWith).

<DxComboBox FilteringMode="DataGridFilteringMode.Contains" ></DxComboBox>

Multiple Columns

The ComboBox can display data across multiple columns. To create columns, use DxListEditorColumn objects that include the following options for column customization:

• FieldName - Specifies the data source field that populates column items.
• Visible - Specifies the column visibility.
• VisibleIndex - Specifies the column display order.
• Width - Specifies the column width.

To format an edit box's value, use the EditFormat property.

<DxComboBox Data="@Persons.DataSource"
            @bind-Value="@SelectedPerson"
            EditFormat ="{1} {2}">
    <DxListEditorColumn FieldName="Id" Width="50px" />
    <DxListEditorColumn FieldName="FirstName" />
    <DxListEditorColumn FieldName="LastName" />
</DxComboBox>

@code {
    Person SelectedPerson { get; set; } = Persons.DataSource[0];
}

Size Modes

Use the SizeMode property to specify the size of a ComboBox. The code below applies different sizes to ComboBox components.

<DxComboBox Data="@Cities"
            NullText="Select City ..."
            @bind-Value="@Value"
            SizeMode="SizeMode.Small">
</DxComboBox>

<DxComboBox Data="@Cities"
            NullText="Select City ..."
            @bind-Value="@Value"
            SizeMode="SizeMode.Medium">
</DxComboBox>

<DxComboBox Data="@Cities"
            NullText="Select City ..."
            @bind-Value="@Value"
            SizeMode="SizeMode.Large">
</DxComboBox>

@code {
    IEnumerable<string> Cities = new List<string>() {
        "London",
        "Berlin",
        "Paris",
    };

    string Value { get; set; }
}

For more information, refer to Size Modes.

Virtual Scrolling

When virtual scrolling is activated (ListRenderMode is set to Virtual), the ComboBox loads data on demand when a user scrolls its items.

<DxComboBox Data="@Strings"
            ListRenderMode="ListRenderMode.Virtual">
</DxComboBox>

Input Validation

You can add a standalone ComboBox or the Form Layout component to the Blazor's standard EditForm. This form validates user input based on data annotation attributes defined in a model and indicates errors.

<EditForm Model="@starship" Context="EditFormContext">
    <DataAnnotationsValidator />
    <DxFormLayout >
        <DxFormLayoutItem Caption="Primary Classification:" ColSpanMd="6" >
            <Template >
                <DxComboBox
                            NullText="Select classification ..."
                            ClearButtonDisplayMode="DataEditorClearButtonDisplayMode.Auto"
                            @bind-Value="@starship.Classification"
                            Data="@(new List<string>() { "Defense", "Exploration", "Diplomacy" })"
                />
            </Template >
        </DxFormLayoutItem >
        @*...*@
    </DxFormLayout>
</EditForm>

@code {
    private Starship starship=new Starship();
}

public class Starship
{
    [Required]
    public string Classification { get; set; }
    // ...
}

For more information, refer to the following help topic: Validate Input.

Read-Only State

<DxComboBox> supports a read-only state. Set the ReadOnly property to true to activate this option.

<DxComboBox ReadOnly="true"> </DxComboBox>

Drop-Down Window Width

Use the DropDownWidthMode property to specify the width of the drop-down list. The following values are available:

• ContentOrEditorWidth (Default) - The list displays item text completely. The minimum list width matches the editor.

  

• ContentWidth - The list width is equal to the width of the longest list item.

  

• EditorWidth - The list width matches the editor. List items are cut if they do not fit.

  

The following code makes the width of the drop-down list equal to the editor width.

@using BlazorApp.Data

<DxComboBox Data="@Persons.DataSource"
            TextFieldName="Text"
            DropDownWidthMode="DropDownWidthMode.EditorWidth">
</DxComboBox>

namespace BlazorApp.Data {
    public class Person {
        public int Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public Department Department { get; set; }
        public string Text => $"{FirstName} {LastName} ({Department} Dept.)";
    }

    public enum Department { Motors, Electronics, Software }
}

using System;
using System.Collections.Generic;

namespace BlazorApp.Data {
    public static class Persons {
        private static readonly Lazy<List<Person>> dataSource = new Lazy<List<Person>>(() => {
            var dataSource = new List<Person>() {
                new Person() { Id= 0 , FirstName="John", LastName="Heart", Department=Department.Electronics },
                new Person() { Id= 1 , FirstName="Samantha", LastName="Bright", Department=Department.Motors },
                new Person() { Id= 2 , FirstName="Arthur", LastName="Miller", Department=Department.Software },
                new Person() { Id= 3 , FirstName="Robert", LastName="Reagan", Department=Department.Electronics },
                new Person() { Id= 4 , FirstName="Greta", LastName="Sims", Department=Department.Motors },
                new Person() { Id= 5 , FirstName="Brett", LastName="Wade", Department=Department.Software },
                new Person() { Id= 6 , FirstName="Sandra", LastName="Johnson", Department=Department.Electronics },
                new Person() { Id= 7 , FirstName="Edward", LastName="Holmes", Department=Department.Motors },
                new Person() { Id= 8 , FirstName="Barbara", LastName="Banks", Department=Department.Software },
                new Person() { Id= 9 , FirstName="Kevin", LastName="Carter", Department=Department.Electronics },
                new Person() { Id= 10, FirstName="Cynthia", LastName="Stanwick", Department=Department.Motors },
                new Person() { Id= 11, FirstName="Sam", LastName="Hill", Department=Department.Electronics },
            return dataSource;
        });
        public static List<Person> DataSource { get { return dataSource.Value; } }
    }
}

Drop-Down Window Direction

Use the DropDownDirection property to specify the direction in which the ComboBox's drop-down window is displayed relative to the input element. The default value is Down. The following code changes the direction to Up:

<DxComboBox Data="@Cities"
            NullText="Select City ..."
            DropDownDirection="DropDownDirection.Up">
</DxComboBox>

@code {
    IEnumerable<string> Cities = new List<string>() {
        "London",
        "Berlin",
        "Paris",
    };
}

HTML Attributes

You can use HTML attributes to configure the ComboBox.

<DxComboBox Data="@Strings" maxlength="10" autofocus> </DxComboBox>