# ListBox

The [Wisej.Web.ListBox](https://docs.wisej.com/api/wisej.web/lists-and-grids/listbox) control displays a list of strings or data-bound values, allowing the user to select one or multiple options.

{% hint style="info" %}
For a full list of properties, methods and events see the [API documentation](https://docs.wisej.com/api/wisej.web/lists-and-grids/listbox).
{% endhint %}

## Features

### Label

The ListBox control supports the inline [Label](https://docs.wisej.com/docs/controls/general/labels) property. This allows an application to set a label in relation to a ListBox control without having to create an additional Label control.

<div align="left"><img src="https://553579532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MF1D11gPs_az3xaKusw%2Fuploads%2Fgit-blob-3454e18fe16123cd2ec312d293cf3026827a1b78%2FListBoxLabel.png?alt=media" alt=""></div>

{% content-ref url="../general/labels" %}
[labels](https://docs.wisej.com/docs/controls/general/labels)
{% endcontent-ref %}

### Data Binding

Data binding is fully supported, including formatting and conversion of the value, through the default [data binding](https://docs.wisej.com/docs/controls/general/data-binding) infrastructure.

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

{% hint style="info" %}
You can use DisplayMember, ValueMember, ToolTipMember and IconMember to name which properties to use from objects in the ListBox.Items list without binding to a DataSource.
{% endhint %}

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.

{% content-ref url="../general/data-binding" %}
[data-binding](https://docs.wisej.com/docs/controls/general/data-binding)
{% endcontent-ref %}

### Selection Modes

The ListBox control allows users to define one of several different selection modes for the control's configuration.

| Selection Mode | Description                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| None           | No items can be selected.                                                                                |
| One            | Only one item can be selected.                                                                           |
| MultiSimple    | Multiple items can be selected.                                                                          |
| MultiExtended  | Multiple items can be selected, and the user can use the SHIFT, CTRL, and arrow keys to make selections. |

You can see the different configuration options shown below.

<div align="left"><img src="https://553579532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MF1D11gPs_az3xaKusw%2Fuploads%2Fgit-blob-263d5d3a1879bc916f985214317f0c3a6091166d%2FListBoxSelectionMode.png?alt=media" alt=""></div>

### Lazy Loading

The ListBox control includes lazy loading support. Lazy loading works by sending the minimum number of records to the browser that is required for display within the control.

Lazy loading will significantly reduce waiting times related to rendering on the browser and network congestion caused by transferring large datasets from the server to the client (browser).

### Virtual Scrolling

The ListBox control has the ability to use virtual scrolling, a feature that only renders the list items currently visible in the browser.

Using this option can drastically reduce the amount of time spent rendering in the browser for large datasets. For a List containing 25,000 strings, the effect will be a noticeable difference of several seconds.

Try the following sample code to test the loading times:&#x20;

{% tabs %}
{% tab title="C#" %}

```csharp
private void Page1_Load(object sender, EventArgs e)
{
	var myList = new List<string>();
	
	for (int i=0; i<25000; i++)
	{
		myList.Add($"String {i}");
	}

	this.listBox1.VirtualScroll = true;
	this.listBox1.DataSource = myList;
}
```

{% endtab %}

{% tab title="VB.NET" %}

```visual-basic
Private Sub Page1_Load(object sender, EventArgs e) Handles Page1.Load

	Dim myList As New List(Of String)
	
	For i = 0 To 25000
		myList.Add($"String {i}")
	Next

	Me.listBox1.VirtualScroll = true
	Me.listBox1.DataSource = myList
	
End Sub
```

{% endtab %}
{% endtabs %}

## How To

### Populate a List

There are a few different ways to populate a ListBox control.

You can add a list of strings using the **Items** property of the ListBox control.

{% tabs %}
{% tab title="C#" %}

```csharp
private void button1_Click(object sender, EventArgs e)
{
	this.listBox1.Items.AddRange(new[] {
		"Eggs",
		"Milk",
		"Carrots"
	});
}
```

{% endtab %}

{% tab title="VB.NET" %}

```visual-basic
Option Strict Off

Private Sub Button1_Click(sender as Object, e As EventArgs) Handles Button1.Click

	Me.listBox1.Items.AddRange({
		"Eggs",
		"Milk",
		"Carrots"
	})
	
End Sub
```

{% endtab %}
{% endtabs %}

Alternatively, you can assign a list of items using the **DataSource** property of the control.

{% tabs %}
{% tab title="C#" %}

```csharp
private void button1_Click(object sender, EventArgs e)
{
	var myList = new List<dynamic>()
	{
		new { id = 1, name = "John" },
		new { id = 2, name = "Jane" },
		new { id = 3, name = "Sally" }
	};

	this.listBox1.ValueMember = "id";
	this.listBox1.DisplayMember = "name";
	
	this.listBox1.DataSource = myList;
}
```

{% endtab %}

{% tab title="VB.NET" %}

```visual-basic
Option Strict Off

Private Sub Button1_Click(sender as Object, e As EventArgs) Handles Button1.Click
{
	Dim myList As New List(Of Object) From
	{
		New With { .id = 1, .name = "John"},
		New With { .id = 2, .name = "Jane"},
		New With { .id = 3, .name = "Sally"}
	}

	Me.listBox1.ValueMember = "id"
	Me.listBox1.DisplayMember = "name"
	Ne.listBox1.DataSource = myList
	
End Sub
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
When assigning a list of complex objects to the **DataSource** or **Items** property, the objects will be converted into their string representations for display in the ListBox control unless the **DisplayMember** property is set.
{% endhint %}

### Add an Icon

**Icon**

Building off of the previous code snippet, it is easy to add an icon to the ListBox items.

{% tabs %}
{% tab title="C#" %}

```csharp
private void button1_Click(object sender, EventArgs e)
{
	var myList = new List<dynamic>()
	{
		new { id = 1, name = "John", icon = "Images/People/1.png" },
		new { id = 2, name = "Jane", icon = "Images/People/2.png" },
		new { id = 3, name = "Sally", icon = "Images/People/3.png" }
	};

	this.listBox1.IconMember = "icon";
	this.listBox1.DisplayMember = "name";
	this.listBox1.DataSource = myList;
}
```

{% endtab %}

{% tab title="VB.NET" %}

```visual-basic
Option Strict Off

Private Sub Button1_Click(sender as Object, e As EventArgs) Handles Button1.Click
{
	Dim myList As New List(Of Object) From
	{
		New With { .id = 1, .name = "John", .icon = "Images/People/1.png" },
		New With { .id = 2, .name = "Jane", .icon = "Images/People/2.png" },
		New With { .id = 3, .name = "Sally", .icon = "Images/People/3.png" }
	}

	Me.listBox1.IconMember = "icon"
	Me.listBox1.DisplayMember = "name"
	Ne.listBox1.DataSource = myList
	
End Sub
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
IconMember, DisplayMember, ToolTipMember, and ValueMember retrieve and set the properties of the clicked data-bound item to use for the icon, text to display, tooltip text, and click value, respectively.
{% endhint %}

The icon paths specified in each object refer to the location of the image relative to the root of the project.

The above code will result in something similar to the following:

<div align="left"><img src="https://553579532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MF1D11gPs_az3xaKusw%2Fuploads%2Fgit-blob-c8bbfa550a084b548637e673ba98b8bf8f2e1993%2FListBoxPeople.png?alt=media" alt=""></div>

### Format a String

If you are working currencies, dates, or other forms of data, you might want to utilize the **FormatString** property of the ListBox control.

{% tabs %}
{% tab title="C#" %}

```csharp
private void button1_Click(object sender, EventArgs e)
{
	var myList = new List<dynamic>()
	{
		new { id = 1, name = "John", payment = 32.53 },
		new { id = 2, name = "Jane", payment = 235.53 },
		new { id = 3, name = "Sally", payment = 45.21 }
	};

	this.listBox1.FormatString = "C2";
	this.listBox1.FormattingEnabled = true;
	this.listBox1.DisplayMember = "payment";
	this.listBox1.DataSource = myList;
}
```

{% endtab %}

{% tab title="VB.NET" %}

```visual-basic
Option Strict Off

Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click

	Dim myList As New List(Of Object) From
	{
		New With { .id = 1, .name = "John", .payment = 32.53 }
		New With { .id = 2, .name = "Jane", .payment = 235.53 }
		New With { .id = 3, .name = "Sally", .payment = 45.21 }
	}

  Me.listBox1.FormatString = "C2"
	Me.listBox1.FormattingEnabled = true
	Me.listBox1.DisplayMember = "payment"
	Me.listBox1.DataSource = myList
	
End Sub
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
You only need to specify **FormattingEnabled** = true when using a **DisplayMember**.
{% endhint %}

The result will look something like this (dependent on system currency):

<div align="left"><img src="https://553579532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MF1D11gPs_az3xaKusw%2Fuploads%2Fgit-blob-1b3830bb827cd5e249e24aa5cc9d3820d76dcc47%2FListBoxPayments.png?alt=media" alt=""></div>

## Advanced

### JavaScript Widget

<table><thead><tr><th width="150">Item</th><th>Description</th></tr></thead><tbody><tr><td>Class name</td><td>wisej.web.ListBox for the ListBox. wisej.web.listbox.ListItem for each list box item.</td></tr><tr><td>Theme appearance</td><td>"list", "listitem" for the items in the list box, see <a href="https://docs.wisej.com/theme-builder/theme-elements/elements">Themes</a>.</td></tr><tr><td>ListBox child components</td><td>"scrollbar-x" is the horizontal scrollbar and "scrollbar-y" is the vertical scrollbar. See <a href="../../concepts/javascript-object-model">JavaScript</a>.</td></tr><tr><td>List item child components</td><td>"checkbox" is the list item's checkbox. "icon" is the list item's icon. See <a href="../../concepts/javascript-object-model">JavaScript</a>.</td></tr><tr><td>ToolContainer state</td><td>"listbox", see <a href="../general/embedded-tools">Embedded Tools</a>.</td></tr><tr><td>Source code</td><td><a href="https://github.com/iceteagroup/wisej-js/blob/master/wisej.web.TextBox.js">https://github.com/iceteagroup/wisej-js</a></td></tr></tbody></table>