Skip to end of metadata
Go to start of metadata

Using text, images, or both, WebListBox unleashes your inner creativity, allowing you to build eye-popping vertical navigators. A rich set of predefined themes provides an endless variety of choices bound to suit every website. For more exacting applications, a comprehensive set of style and layout properties enables you to create navigation set to your own precise specifications in mere minutes.

On this page:

User Interface

WebListBox is a unique control, part of WebEssentials family, which can be used as an input control or a navigation control. It contains a list of items displayed vertically and users can select single or multiple items.

Built to support XHTML and HTML doctype, WebListBox provides limitless customizations on the user interface aspect through its comprehensive properties. Furthermore, the UI personalization can be made globally (specified in LayoutSettings property) or item specific depending on your need.

Scroll Mode

Scroll mode option is provided to anticipate having many items in WebListBox which exceeds the container's height. The common practice is to use scrollbar. WebListBox offers several scroll options, Scroller, ScrollBar, or None, that you can set in LayoutSettings >> ScrollMode property.

The Scroller scroll mode displays two directional arrows, up and down, that when users hover on it, all items will be scrolled. The ScrollBar scroll mode displays a vertical scrollbar, and the None option shows nothing. Hidden items remain invisible.

To learn more about Scroll mode, see How-to: Configure Scroll mode in WebListBox.

Selection Mode

The nature of WebListBox is as an input control where users can select not only one item, but multiple items at a time. This behavior can be configured in SelectionMode property. Single mode lets users to select only one item at a time. In Multiple mode, users can select multiple items by selecting a range using mouse, or using the keyboard + mouse combo to perform the selections. It works with CTRL and SHIFT.

To learn more about Selection mode, see How-to: Configure Selection Mode in WebListBox.

Set Selected Item(s) On Load

Initial item selections feature is essential for certain scenarios. To achieve this, simply set the [Item].Selected property to True or the SelectedIndex property to the selected item's index.

In Single selection mode with SelectedIndex property set, any items' Selected property setting is ignored. In Multiple mode, you can either use the SelectedIndex property or Item's Selected property to make the selection.

Additionally, selected items can be defined using SetValue and SetValues server-side methods.

To learn more about Selected item, see How-to: Set Selected Item on Load.

Get Selected Value

The selected item's index and value can be retrieved using Value and SelectedIndex property. When Multiple selection mode is active, use the GetValues server-side method to retrieve all selected values.

To learn more about Selected values, see How-to: Get Selected Values in Button Click.

Enable Keyboard Support

In addition to use mouse, users can use keyboard keys to select an item(s). Set the EnableKeyboardSupport property to True and users will be able to swiftly move through the items using up and down directional keys. Item will be automatically selected as users navigate using keyboard.


This property does not need to be enabled in order to use Ctrl and Shift keys when Multiple selection mode is enabled.


WebListBox has built-in AutoPostBack property for client-server communication. When enabled, postback will be triggered as the selected item is changed. You can perform FullPostBack or FlyPostBack, customizable in PostBackMode property.

When postback is enabled, OnSelectedItemChanged server-side event is raised. This enables you to apply your programmatic processing. It allows you to obtain the selected items' index via the event arguments.





This configuration will be ignored when the selection mode is set to Multiple.

To learn more about AutoPostBack, see How-to: Enable AutoPostBack in WebListBox.

To learn more about getting selected value on AutoPostBack, see How-to: Get Selected Values when AutoPostBack is enabled.


Despite its nature as an input control, WebListBox can also be used as a navigation control. When an item is clicked, the specified URL will be opened in a new window or target IFrame. The target window can be specified in LayoutSettings >> TargetWindow property or [item] >> TargetWindow property for individual item. The target URL can be specified in [item] >> TargetURL property.


This configuration will be ignored when the selection mode is set to Multiple.

To learn more about Navigation, see How-to: Configure Navigation in WebListBox.


WebListBox supports various colorful and modern looking visual themes that you can select easily.

Client-side Events


OnInitialize()Invoked during the control initialization process.
OnItemMouseOver()Invoked when an item is hovered.
OnItemMouseOut()Invoked when mouse out action is performed on an item.
OnKeyUp()Invoked during key up action.
OnResponse()Invoked when a response is returned after a FlyPostBack action.
OnResponseError()Invoked if there is an error during a FlyPostBack action.
OnBeforeItemSelected()Invoked before the item(s) are selected.
OnAfterItemSelected()Invoked after item(s) are selected.

Data Binding

Targeting enterprise Web applications, WebListBox is enhanced with data binding to data source control capability. WebListBox can be bound using traditional binding and datasource control.

Several properties related to data binding functionality are listed below.

DataSourceIDThe data source id of WebListBox.
DataMemberThe data member of WebListBox.
NameFieldDataMemberThe field data member of Name property.
ImageFieldDataMemberThe field data member of Image property.
TextFieldDataMemberThe field data member of Text property.
ValueFieldDataMemberThe field data member of Value property.
TargetURLFieldDataMemberThe field data member of TargetURL property.
ImageFieldFormatStringThe format string of Image field data member.

The related properties will be bound automatically when the field data member is specified. WebListBox also supports unbound mode. You need to add the items manually.

To learn more about Bind DataSource to WebListBox, see How-to: Bind DataSource to WebListBox.

To learn more about Unbound WebListBox, see How-to: Create Unbound WebListBox.

Rich Client-side APIs


GetElementGets frame element of WebListBox.
GetContentFrameElementGets the content frame element of WebListBox.
GetContentElementGet the content element of WebListBox.
GetIndicatorElementGets the triangle indicator element.
GetTopScrollerElementGets the content frame element of the top scroller.
GetTopScrollerGets the top scroller element.
GetBottomScrollerElementGets the content frame element of the bottom scroller.
GetBottomScrollerGets the bottom scroller element.
GetItemByValueGets a specific item by value.
GetSelectedIndexesGets the collection of selected item's indexes.
DoResizePerforms resize in WebListBox.