ListBox Class (System.Web.UI.WebControls)

Switch View :
Classic
Lightweight
ScriptFree
.NET Framework Class Library
ListBox Class

Represents a list box control that allows single or multiple item selection.

Namespace: System.Web.UI.WebControls
Assembly: System.Web (in system.web.dll)

Syntax
Visual Basic (Declaration)
<ValidationPropertyAttribute("SelectedItem")> _
Public Class ListBox
	Inherits ListControl
	Implements IPostBackDataHandler
Visual Basic (Usage)
Dim instance As ListBox
C#
[ValidationPropertyAttribute("SelectedItem")] 
public class ListBox : ListControl, IPostBackDataHandler
C++
[ValidationPropertyAttribute(L"SelectedItem")] 
public ref class ListBox : public ListControl, IPostBackDataHandler
J#
/** @attribute ValidationPropertyAttribute("SelectedItem") */ 
public class ListBox extends ListControl implements IPostBackDataHandler
JScript
ValidationPropertyAttribute("SelectedItem") 
public class ListBox extends ListControl implements IPostBackDataHandler
Remarks

Use the ListBox control to create a list control that allows single or multiple item selection. Use the Rows property to specify the height of the control. To enable multiple item selection, set the SelectionMode property to ListSelectionMode.Multiple.

Use the Items collection to examine the ListItem objects contained in the ListBox control. For example, you can determine the selected item(s) in the ListBox control by enumerating the Items collection and testing the Selected value for each ListItem element.

Caution noteCaution

This control can be used to display user input, which might include malicious client script. Check any information that is sent from a client for executable script, SQL statements, or other code before displaying it in your application. You can use validation controls to verify user input before displaying the input text in a control. ASP.NET provides an input request validation feature to block script and HTML in user input. For more information, see Securing Standard Controls, How to: Protect Against Script Exploits in a Web Application by Applying HTML Encoding to Strings, and Validating User Input in ASP.NET Web Pages.

Accessibility

The markup rendered by default for this control might not conform to accessibility standards such as the Web Content Accessibility Guidelines 1.0 (WCAG) priority 1 guidelines. For details about accessibility support for this control, see ASP.NET Controls and Accessibility.

Example

The following example demonstrates how to create a ListBox control.

Visual Basic
<%@ Page Language="VB" AutoEventWireup="True" %>

<html>
<head>

   <script language="VB" runat="server">

    Sub SubmitBtn_Click(sender As Object, e As EventArgs)
        If ListBox1.SelectedIndex > - 1 Then
            Label1.Text = "You chose: " & ListBox1.SelectedItem.Text
        End If
    End Sub 'SubmitBtn_Click

  </script>

</head>
<body>

   <h3>ListBox Example</h3>

   <form runat=server>

      <asp:ListBox id="ListBox1" 
           Rows="6"
           Width="100px"
           SelectionMode="Single" 
           runat="server">

         <asp:ListItem>Item 1</asp:ListItem>
         <asp:ListItem>Item 2</asp:ListItem>
         <asp:ListItem>Item 3</asp:ListItem>
         <asp:ListItem>Item 4</asp:ListItem>
         <asp:ListItem>Item 5</asp:ListItem>
         <asp:ListItem>Item 6</asp:ListItem>

      </asp:ListBox>

      <asp:button id="Button1"
           Text="Submit" 
           OnClick="SubmitBtn_Click" 
           runat="server" />
        
      <asp:Label id="Label1" 
           Font-Name="Verdana" 
           Font-Size="10pt" 
           runat="server"/>
        
   </form>

</body>
</html>
C#
<%@ Page Language="C#" AutoEventWireup="True" %>

<html>
<head>

   <script language="C#" runat="server">

      void SubmitBtn_Click(Object sender, EventArgs e) 
      {
         if (ListBox1.SelectedIndex > -1)
            Label1.Text="You chose: " + ListBox1.SelectedItem.Text;
      }

   </script>

</head>
<body>

   <h3>ListBox Example</h3>

   <form runat=server>

      <asp:ListBox id="ListBox1" 
           Rows="6"
           Width="100px"
           SelectionMode="Single" 
           runat="server">

         <asp:ListItem>Item 1</asp:ListItem>
         <asp:ListItem>Item 2</asp:ListItem>
         <asp:ListItem>Item 3</asp:ListItem>
         <asp:ListItem>Item 4</asp:ListItem>
         <asp:ListItem>Item 5</asp:ListItem>
         <asp:ListItem>Item 6</asp:ListItem>

      </asp:ListBox>

      <asp:button id="Button1"
           Text="Submit" 
           OnClick="SubmitBtn_Click" 
           runat="server" />
        
      <asp:Label id="Label1" 
           Font-Name="Verdana" 
           Font-Size="10pt" 
           runat="server"/>
        
   </form>

</body>
</html>

The following example demonstrates how to create a ListBox control through data binding.

Visual Basic
<%@ Page Language="VB" AutoEventWireup="True" %>

<html>
<head>

   <script language="VB" runat="server">

    Sub Page_Load(sender As Object, e As EventArgs)
        
        If Not IsPostBack Then
            
            Dim values As New ArrayList()
            
            values.Add("Item 1")
            values.Add("Item 2")
            values.Add("Item 3")
            values.Add("Item 4")
            values.Add("Item 5")
            values.Add("Item 6")
            
            ListBox1.DataSource = values
            ListBox1.DataBind()
        End If 
    End Sub 'Page_Load

    Sub SubmitBtn_Click(sender As Object, e As EventArgs)
        
        If ListBox1.SelectedIndex > - 1 Then
            Label1.Text = "You chose: " & ListBox1.SelectedItem.Text
        End If 
    End Sub 'SubmitBtn_Click

  </script>

</head>
<body>

   <form runat=server>

        <h3>Data Binding ListBox</h3>
    
        <asp:ListBox id="ListBox1" 
             Width="100px" 
             runat="server"/>

        <asp:button id="Button1"
             Text="Submit" 
             OnClick="SubmitBtn_Click" 
             runat="server" />
        
        <asp:Label id="Label1" 
             font-name="Verdana" 
             font-size="10pt" 
             runat="server"/>

   </form>

</body>
</html>
C#
<%@ Page Language="C#" AutoEventWireup="True" %>

<html>
<head>

   <script language="C#" runat="server">

      void Page_Load(Object sender, EventArgs e) 
      {

         if (!IsPostBack) 
         {

            ArrayList values = new ArrayList();

            values.Add ("Item 1");
            values.Add ("Item 2");
            values.Add ("Item 3");
            values.Add ("Item 4");
            values.Add ("Item 5");
            values.Add ("Item 6");

            ListBox1.DataSource = values;
            ListBox1.DataBind();

         }

      }

      void SubmitBtn_Click(Object sender, EventArgs e) 
      {
      
         if ( ListBox1.SelectedIndex > -1 )
            Label1.Text = "You chose: " + ListBox1.SelectedItem.Text;
         
      }

   </script>

</head>
<body>

   <form runat=server>

        <h3>Data Binding ListBox</h3>
    
        <asp:ListBox id="ListBox1" 
             Width="100px" 
             runat="server"/>

        <asp:button id="Button1"
             Text="Submit" 
             OnClick="SubmitBtn_Click" 
             runat="server" />
        
        <asp:Label id="Label1" 
             font-name="Verdana" 
             font-size="10pt" 
             runat="server"/>

   </form>

</body>
</html>
.NET Framework Security
Inheritance Hierarchy
System.Object
   System.Web.UI.Control
     System.Web.UI.WebControls.WebControl
       System.Web.UI.WebControls.BaseDataBoundControl
         System.Web.UI.WebControls.DataBoundControl
           System.Web.UI.WebControls.ListControl
            System.Web.UI.WebControls.ListBox
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Platforms

Windows 98, Windows 2000 SP4, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

Version Information

.NET Framework

Supported in: 2.0, 1.1, 1.0
See Also
Community Content

PepperedApple
Styling the ListBox
The ListBox control will render an html select control.  This means that it is subject to the same styling constraints as the <select> tag.  The <select> tag will always display on top of other html, even if you set z-order and absolute positioning.