ListBox Class (System.Web.UI.WebControls)

Switch on low bandwidth view

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.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")> _
<AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level := AspNetHostingPermissionLevel.Minimal)> _
<AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level := AspNetHostingPermissionLevel.Minimal)> _
Public Class ListBox _
    Inherits ListControl _
    Implements IPostBackDataHandler

Visual Basic (Usage)

Dim instance As ListBox

[ValidationPropertyAttribute("SelectedItem")]
[AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level = AspNetHostingPermissionLevel.Minimal)]
[AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level = AspNetHostingPermissionLevel.Minimal)]
public class ListBox : ListControl, IPostBackDataHandler

Visual C++

[ValidationPropertyAttribute(L"SelectedItem")]
[AspNetHostingPermissionAttribute(SecurityAction::LinkDemand, Level = AspNetHostingPermissionLevel::Minimal)]
[AspNetHostingPermissionAttribute(SecurityAction::InheritanceDemand, Level = AspNetHostingPermissionLevel::Minimal)]
public ref class ListBox : public ListControl, 
    IPostBackDataHandler

JScript

public class ListBox extends ListControl implements IPostBackDataHandler

ASP.NET

<asp:ListBox />

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:
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.

Caution:

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.

Topic	Location
How to: Add Items in List Web Server Controls	Building ASP .NET Web Applications
How to: Add Items in List Web Server Controls	Building ASP .NET Web Applications
How to: Add Items in List Web Server Controls	Building ASP .NET Web Applications in Visual Studio
How to: Add Items in List Web Server Controls	Building ASP .NET Web Applications in Visual Studio
How to: Add Items in List Web Server Controls (Visual Studio)	Building ASP .NET Web Applications in Visual Studio
How to: Add ListBox Web Server Controls to a Web Forms Page	Building ASP .NET Web Applications
How to: Add ListBox Web Server Controls to a Web Forms Page	Building ASP .NET Web Applications
How to: Add ListBox Web Server Controls to a Web Forms Page	Building ASP .NET Web Applications in Visual Studio
How to: Add ListBox Web Server Controls to a Web Forms Page	Building ASP .NET Web Applications in Visual Studio
How to: Add ListBox Web Server Controls to a Web Forms Page (Visual Studio)	Building ASP .NET Web Applications in Visual Studio
How to: Determine the Selection in List Web Server Controls	Building ASP .NET Web Applications
How to: Determine the Selection in List Web Server Controls	Building ASP .NET Web Applications
How to: Determine the Selection in List Web Server Controls	Building ASP .NET Web Applications in Visual Studio
How to: Determine the Selection in List Web Server Controls	Building ASP .NET Web Applications in Visual Studio
How to: Populate List Web Server Controls from a Data Source	Building ASP .NET Web Applications
How to: Populate List Web Server Controls from a Data Source	Building ASP .NET Web Applications
How to: Populate List Web Server Controls from a Data Source	Building ASP .NET Web Applications in Visual Studio
How to: Populate List Web Server Controls from a Data Source	Building ASP .NET Web Applications in Visual Studio
How to: Populate List Web Server Controls from a Data Source (Visual Studio)	Building ASP .NET Web Applications in Visual Studio
How to: Respond to Changes in List Web Server Controls	Building ASP .NET Web Applications
How to: Respond to Changes in List Web Server Controls	Building ASP .NET Web Applications
How to: Respond to Changes in List Web Server Controls	Building ASP .NET Web Applications in Visual Studio
How to: Respond to Changes in List Web Server Controls	Building ASP .NET Web Applications in Visual Studio
How to: Set Focus on ASP.NET Web Server Controls	Building ASP .NET Web Applications
How to: Set Focus on ASP.NET Web Server Controls	Building ASP .NET Web Applications
How to: Set Focus on ASP.NET Web Server Controls	Building ASP .NET Web Applications in Visual Studio
How to: Set Focus on ASP.NET Web Server Controls	Building ASP .NET Web Applications in Visual Studio
How to: Set the Selection in List Web Server Controls	Building ASP .NET Web Applications
How to: Set the Selection in List Web Server Controls	Building ASP .NET Web Applications
How to: Set the Selection in List Web Server Controls	Building ASP .NET Web Applications in Visual Studio
How to: Set the Selection in List Web Server Controls	Building ASP .NET Web Applications in Visual Studio
How to: Set the Selection in List Web Server Controls (Visual Studio)	Building ASP .NET Web Applications in Visual Studio
Walkthrough: Creating and Using ASP.NET Master Pages in Visual Web Developer	Building ASP .NET Web Applications in Visual Studio
Walkthrough: Creating and Using ASP.NET Master Pages in Visual Web Developer	Building Applications with Visual Web Developer
Walkthrough: Creating and Using ASP.NET Master Pages in Visual Web Developer	Building ASP .NET Web Applications in Visual Studio
Walkthrough: Creating Reusable Elements with ASP.NET User Controls	Building ASP .NET Web Applications in Visual Studio
Walkthrough: Creating Reusable Elements with ASP.NET User Controls	Building Applications with Visual Web Developer
Walkthrough: Creating Reusable Elements with ASP.NET User Controls	Building ASP .NET Web Applications in Visual Studio
Walkthrough: Data Binding to a Custom Business Object	Building ASP .NET Web Applications in Visual Studio
Walkthrough: Data Binding to a Custom Business Object	Building ASP .NET Web Applications in Visual Studio
Walkthrough: Data Binding to a Custom Business Object	Building ASP .NET Web Applications in Visual Studio

Examples

The following example demonstrates how to create a ListBox control.

Visual Basic

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html  >
<head>
    <title>ListBox Example</title>
<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 id="form1" 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-Names="Verdana" 
           Font-Size="10pt" 
           runat="server"/>

   </form>

</body>
</html>

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html  >
<head>
    <title>ListBox Example</title>
<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 id="form1" 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-Names="Verdana" 
           Font-Size="10pt" 
           runat="server"/>

   </form>

</body>
</html>

The following example shows how to create a ListBox control that supports multiple selections.

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

Visual Basic

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html  >
<head>
    <title>Data Binding ListBox</title>
<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 id="form1" 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-Names="Verdana" 
             font-size="10pt" 
             runat="server"/>

   </form>

</body>
</html>

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html  >
<head>
    <title>Data Binding ListBox</title>
<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 id="form1" 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-Names="Verdana" 
             font-size="10pt" 
             runat="server"/>

   </form>

</body>
</html>

.NET Framework Security

AspNetHostingPermission
for operating in a hosted environment. Demand value: LinkDemand. Permission value: Minimal.
AspNetHostingPermission
for operating in a hosted environment. Demand value: InheritanceDemand. Permission value: Minimal.

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 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

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

Version Information

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

Reference

ListBox Members

System.Web.UI.WebControls Namespace

ListControl

ListItem

ListItemCollection

Other Resources

ListBox Web Server Control Overview

Securing Standard Controls

How to: Protect Against Script Exploits in a Web Application by Applying HTML Encoding to Strings

Tags

: Add a tag

Community Content

Add new content

Annotations

SelectedIndex is flawed

Landrover S3 ... Thomas Lee | Edit | Show History

If the value property is set to the same value such as "3" for multiple ListItems then the ListBox.SelectedIndex does not reflect reality.....

MS - please update your documentation to warn against this design flaw - basically you have misimplemented SelectedIndex :-)

Tags

: contentbug? (x) Add a tag

Flag as ContentBug

Multiple selected items and setting the ListItem.Value to a non distinct value

cyberax ... Thomas Lee | Edit | Show History

Microsoft please please either fix or warn others that ListItem.value has to be unique for each item in order for multiple selected items to work. Why do it like this? Myself and 2 developers have just spent the last x hours of debugging to work that out.

Tags

: contentbug (x) Add a tag

Flawed implementation of ListItems

gotamaofborg | Edit | Show History

The work-around appears to be to peak into the HTTP Request form items & parse it for yourself!

e.g. (in Vis. Basic)

Me.Request.Form.Item("Listbox1") will return a parsable string: "Item 03,Item 03"

I guess developers would just write a nifty little structure or class to enum thru the list... now just don't be putting commas in your data values... ;-)

So... when is a .selected not a .selected? When Microsoft wants to de-duplicate selected values, without warning us!

Perchance there's some kind of global setting to prevent this kind of fuzzy UI object behavior?

Tags

: bug (x) functional (x) Add a tag

Flag as ContentBug