Skip to main content

ComboBox

WATCH & LEARN0:50 · Animated tutorial
7 scenesPlay, pause, or scrub at your own pace

The Wisej.Web.ComboBox control displays a text box combined with a ListBox, which enables the user to select items from the list or enter a new value. Items in the drop-down list can be objects of any type. The list displays a string representation of each item.

info

For a full list of properties, methods and events see the API documentation.

Features​

Label​

The ComboBox control supports the inline Label property. This allows an application to set a label in relation to a ComboBox control without having to create an additional Label control.

Labels

Editing​

There are three DropDownStyle options that determine whether the user can edit the value in the ComboBox or must select an item from the drop down list:

  • DropDown. The ComboBox is editable, the user can either pick an item from the list or enter any value in the editable control. If the value entered by the user is not in the list, the SelectedIndex value will be -1.
  • DropDownList. The ComboBox is not editable, the user must pick an item from the list.
  • Simple. The ComboBox is editable, like the DropDown option, but the drop down list is always visible making the ComboBox display like a TextBox on top of a ListBox.

AutoComplete Modes​

There are six auto complete modes supported by the ComboBox control:

  • None (Default). There is no auto complete. The user can type anything and the control will not auto select or suggest any item in the list.
  • Suggest. Causes the drop down list to open automatically as soon as the user starts typing and scrolls the list to show the items that start with the edited text. However, it doesn't select any item.
  • Append. Automatically completes the text with the full text of the first item that starts with the typed text and highlights the remaining portion of the text. It doesn't select any item, it only completes the text as it's typed. It doesn't open the drop down list, but if the list is already opened it also scrolls the list to show the items that match the text.
  • SuggestAppend. It's the combination of Suggest and Append. It opens the drop down list as soon as the user starts typing and completes the text being entered with the text of the first matching item.
  • Filter. Automatically opens the list when the user starts typing and filters the items in the list to show only the items that start with the text being typed. See Custom Item Filtering to implement custom filters.
  • AppendFilter. It is the combination of Filter and Append. Automatically opens the list when the user starts typing and filters the items in the list to show only the items that start with the text being typed, and completes the typed text with the first matching item. See Custom Item Filtering to implement custom filters.

Data Binding​

Data binding is fully supported, including formatting and conversion of the value, through the default data binding infrastructure. For the ComboBox the default data property is Text.

In addition to binding the value (Text, or SelectedItem or SelectedValue bindable properties), the ComboBox control also supports data binding to populate the drop down list using the DataSource property in conjunction with the DisplayMember, ValueMember, ToolTipMember and IconMember properties.

info

You can use DisplayMember, ValueMember, ToolTipMember and IconMember to name which properties to use from objects in the ComboBox.Items list without binding to a DataSource.

When the ShowToolTips property is set to true, the ComboBox control uses the name specified in the ToolTipMember to read the tooltip text to display next to each item in the drop down list.

this.comboBox1.IconMember = "Icon";
this.comboBox1.ValueMember = "ID";
this.comboBox1.DisplayMember = "Name";
this.comboBox1.ToolTipMember = "Tooltip";

this.comboBox1.Items.Add(
	new
	{
		ID = 1,
		Name = "Wisej",
		Icon = "icon-print",
		Tooltip = "Tooltip for item 1"
	});

this.comboBox1.Items.Add(
	new
	{
		ID = 12,
		Name = "Blazor",
		Icon = "icon-exit",
		Tooltip = "Tooltip for item 2"
	});

The code above shows how to add custom objects to the drop down list and bind to their properties.

Data Binding

Spell Checking​

You can enable the browser's built-in spell checking by setting the SpellCheck property to true.

This functionality is entirely based on the browser's current language and spell checking support. If you need to use a third party spell checking you can, but it's outside of the Wisej.NET functionality.

Tool Buttons​

Use the Tools property to add internal buttons aligned to the left or right. Handle their clicks through the ToolClick event.

For the ComboBox, the tools are located to the left of the drop down button (arrow).

Embedded Tools

Lazy Events​

Some events exposed by the ComboBox control are fired only when there is a handler attached to the event. This feature prevents the browser from sending frequent events unless the application has explicitly subscribed to the event.

For example, the KeyDown event is a Lazy Event, otherwise the browser would fire an ajax request every time the user typed a character in the ComboBox.

If you extend a control class and override the On[EventName] method to handle a lazy event without attaching a handler, your code will not be called unless there is a handler attached to the event.

Events

Watermark​

Displays a background text in the control when there is no item selected. The watermark text is replaced by the selected item's text and it's restored when the SelectedIndex is reset to -1.

Wisej.NET renders the watermark property to the placeholder HTML attribute, if it's supported by the browser, otherwise it creates an overlaid label entirely managed by the Wisej.NET JavaScript library.

Character Casing​

Use the CharacterCasing property to force the browser and the server to change the casing of the text entered by the user. Wisej.NET performs the transformation on the client when typing and on the server when assigning the Text property.

HTML Text​

Use the AllowHtml property to render the text in the items as plain HTML. This feature allows an application to render any type of content in the drop down list.

An item with this text "<big><big><big>A</big></big></big>ustralia" is rendered like this:

info

Wisej.NET uses the plain text version of the item's HTML text for item filtering, and the AutoCompleteMode options.

How To​

Filter keyboard input​

Unlike the TextBox control, the ComboBox doesn't provide a Filter property. You can, however, attach to the "keydown" JavaScript event on the client and filter the keyboard input.

It is not possible to stop the <input> element from accepting a character by handling the KeyDown event on the server side - the event has already happened and it has already been processed by the browser by the time it reaches the server.

For example, to allow the user to only type alphabetical characters in the range a-z or A-Z add a handler for the keydown event and prevent the default processing by the browser when the typed character doesn't match the expression.

Customize the appearance​

There are several ways to customize the appearance of a ComboBox: set appearance properties, customize the theme, or add custom styles.

The properties that can change the appearance of a ComboBox (and most controls) are usually limited to BackColor, ForeColor, BorderStyle, and Font properties.

If you need to achieve some very special UI design, like the Material-3 animated underline when the ComboBox gains the focus, you will have to either create a custom theme, or a theme mixin or add custom styles to the control.

You can see in the image above a ComboBox with "border:2px solid green;border-radius:20px" assigned to the CssStyle property. To apply a shared style, set the CssClass property instead and add a StyleSheet file (.css) to the application either in Default.html or using the StyleSheet extender.

Change the size of the items​

The minimum height of the items in the drop down list is set in the theme under the "combobox" appearance: combobox/states/default/properties/itemHeight.

However, the rendered height in the browser depends on the content of each item and the font. You can change the minimum height either in the theme or programmatically by setting the ComboBox.ItemHeight property, in pixels.

Advanced​

Lazy Loading​

By default, a ComboBox sends all its items to the browser when the widget is created. For a large list, this can transfer substantial data even if the user only reads the selected value and never opens the list. Lazy loading defers that transfer until the list is needed.

Set the LazyLoading property to true and Wisej.NET will take care of the rest. It will show the selected item as if the list is already populated and, when the user opens the list, it will show an ajax loader icon over the drop down button while it retrieves the items from the server.

If the ComboBox.Items collection is already populated, Wisej.NET sends back to the browser all the items in the list. However, when LazyLoading is true, it also fires the Load event allowing the application to add items to the list the first time it's opened by the user.

info

While the Load event is fired only the first time a LazyLoading ComboBox is opened, the DropDown event is always fired, with or without LazyLoading, giving your app a chance to update the items list every time the user opens the drop down list.

Virtual Scrolling​

A ComboBox can contain very large lists, but creating a browser widget for every item can affect performance. Virtual scrolling reduces this rendering work by creating widgets for the visible portion of the list.

For the ComboBox, ListBox, and TreeView it's the VirtualScroll property. Set VirtualScroll to true so the JavaScript widget renders only visible items, reducing the browser's rendering work for large lists.

Custom Item Rendering​

Override the dynamic RenderItem(object item) method to implement your custom rendering of the items in the list. This method is called for each item in the list and returns a dynamic object representing the corresponding widget in the list. Since each item is an actual widget, the rendering object can specify any valid widget property.

For example, if you have a ComboBox that shows a list of strings (countries) and you want to show all the ones that start with "A" with a yellow background and the ones that start with "B" with a blue background:

This is the simple override:

protected override dynamic RenderItem(object item)
{
		var config = base.RenderItem(item);
		
		var text = (string)item;
		if (text.StartsWith("A"))
			config.backgroundColor = "yellow";
		else if (text.StartsWith("B"))
			config.backgroundColor = "cyan";

		return config;
}
warning

Remember that in VB.NET you need to use Option Strict Off for dynamic objects or use the indexer for the fields of the dynamic object.

Custom Item Filtering​

Items in the drop down list are filtered as the user types when the AutoCompleteMode is set to either Filter or AppendFilter. The built-in filter matches the starting text of the items in a case insensitive comparison.

If you want to implement a different filtering algorithm you can do it simply by overriding the onFilterListItem(label, text) JavaScript function in the wisej.web.ComboBox JavaScript class. You can install the method override on a specific control, or you can patch the wisej.web.ComboBox class, or you can create a new custom JavaScript class.

To install a specific custom filter on a ComboBox control, add your JavaScript override to the InitScript property:

Return true to include the item represented by label or false to remove it from the list.

JavaScript Widget​

ItemDescription
Class name"wisej.web.ComboBox" or "wisej.web.VirtualComboBox" when VirtualScroll is true.
Theme appearance"combobox", "listitem" for the items in the drop down, see Themes.
Child components"textfield" is the inner <input> widget, "button" is the drop down button, "list" is the drop down list, "popup" is the container of the drop down list, "labelfield" is the inner content when the ComboBox is not editable, and "icon" is the icon for the selected item when it shows an icon. See JavaScript.
ToolContainer state"editor", see Embedded Tools.
Source codehttps://github.com/iceteagroup/wisej-js