Selected item: { FirstName=Nancy, LastName=Davolio, Title=Sales Representative }

The ComboBox is an editor that allows users to select an item from a drop-down list. Users can click an item in the drop-down list or use the ARROW UP, ARROW DOWN, and ENTER keys to navigate between items and select them. When a user presses and holds an arrow key, the editor's window continuously navigates between items.

The main ComboBox API members are listed below:

  • Data — Specifies the data source that populates the editor's list items.
  • TextFieldName — Specifies the data source's field that supplies text for items.
  • Text — Specifies the editor's text.
  • TextChanged — Fires when the editor text was changed.
  • Value — Specifies the drop-down list's selected value.
  • ValueChanged — Fires when the selected value was changed.

The ComboBox component supports different size modes. To specify the component's size in code, use the SizeMode property. To apply different size modes, use the drop-down list in the demo card's header.

This demo illustrates how to bind the ComboBox to a list of complex business objects.

Virtual Scrolling

Selected item: null

Use the ListRenderMode property to specify how the ComboBox renders the item list.

  • Entire — The ComboBox renders the entire item list. Use this option for small item lists where scrolling should work instantly.
  • Virtual — The ComboBox renders items only after they appear in the viewport. Use this option to improve performance when the list contains too many items to render simultaneously.

In this demo, the ListRenderMode property is set to ListRenderMode.Virtual.

Multiple Columns

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

  • Caption — Specifies the column caption.
  • 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 editor value, use the EditFormat property. This property allows you to format values displayed in both ordinary and multi-column ComboBoxes. The {1} {2} format specifies that the editor value includes values of the following columns: Name (VisibleIndex = 1) and Surname (VisibleIndex = 2).

Allow Input

Selected item: null, Text = New York

The AllowUserInput property specifies whether users are allowed to input values into an editor's edit box. The following property values are available:

  • true — A user can either select an item from the drop-down list or enter new values into the edit box (without the need to invoke the drop-down list).
  • false — A user can only select an item from the drop-down list.

In this demo, the AllowUserInput property is set to true.

Incremental Filtering

Use the FilteringMode property to specify whether and how the ComboBox filters list items when users type in the edit box.

  • Contains — The ComboBox filters list items that contain the search string and highlights matches.
  • StartsWith — The ComboBox filters list items that begin with the search string and highlights matches.
  • None — The ComboBox does not filter list items.

In this demo, the filter mode is set to DataGridFilteringMode.StartsWith. To change the filter mode or disable filtering, use the Filtering Mode drop-down list.

Use the DropDownWidthMode property to specify the width of a drop-down list.

  • ContentOrEditorWidth (Default) — The list's width is equal to the width of the longest list item or the editor's width (whichever is larger).
  • ContentWidth — The list's width is equal to the width of the longest list item.
  • EditorWidth — The list's width is equal to the editor's width. List items are cut if they do not fit.

In this demo, ContentOrEditorWidth mode is used for both ComboBox components. To change the width of their drop-down lists, use the Drop Down Width Mode option below.

Clear Button and Placeholder

This demo illustrates how to use the NullText property to display the placeholder text in the ComboBox when its value is null.

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

Item Values

Selected value: 1

The ComboBox component provides access to item values. The value is assigned to the editor's edit value when a user selects an item from the drop-down list. To enable this access, set the ValueFieldName property to the name of the data source field that ships with values for the ComboBox items.

If the ValueFieldName property is not specified, the ComboBox component searches for a Value field in the data source and uses this field as a value field. Otherwise, values are not assigned to editor items.

To access a selected item's value, use the Value property. To track selection changes, use the ValueChanged event or two-way synchronization as demonstrated in this module.

Item Template

Use the ItemTemplate property to customize the appearance of individual items displayed within the DevExpress ComboBox component. The template's context parameter allows you to access a data object and its fields.

In this demo, the ItemTemplate property is used to display the ComboBox's items in a card-like view. Each item shows an employee's first name, last name, photo, and phone number.

Edit Box Template

Use the EditBoxTemplate property to customize the appearance of items displayed within the edit box. The template's context parameter allows you to access a data object and its associated fields.

To create an edit box template with user input and filter mode support, declare the DxInputBox object within the EditBoxTemplate markup and enable the DxComboBox.AllowUserInput and DxComboBox.FilteringMode properties.

In this demo, the EditBoxTemplate property is used to display the ComboBox item and its icon within the edit box. The template contains the DxInputBox component and allows users to enter text in the edit box and filter data as needs dictate (Note: for this demo, we've enabled the StartsWith filter mode).

Cascading Lists

This demo shows how to populate the ComboBox with items based on the user selection in another ComboBox.