System.Web.UI.WebControls Namespace

---

Represents an option item in a selectable list control.

ListItem Class Members

Show Inherited Members

Constructors Visibility Constructor Parameters public ListItem ( ) public ListItem ( String text ) public ListItem ( String text , String value ) public ListItem ( String text , String value , Boolean enabled )   Properties Visibility Name Value Type Accessibility public Attributes AttributeCollection [ Get ] public Enabled Boolean [ Get , Set ] public Selected Boolean [ Get , Set ] public Text String [ Get , Set ] public Value String [ Get , Set ]   Methods Visibility Name Parameters Return Type public Equals ( Object o ) Boolean public static FromString ( String s ) ListItem public GetHashCode ( ) Int32 public ToString ( ) String

A ListItem control represents an individual data item within a data-bound control that derives from the base ListControl class. These include the CheckBoxList, DropDownList, ListBox, and RadioButtonList controls.

There are several ways to specify the text displayed for an item in the list control. The most common method is by placing text in the inner HTML content. The inner HTML content is the text between the opening and closing tags of the ListItem control. You can also use the Text property to specify the text displayed in the list control for the item.

The Value property allows you to associate a value with the item in the list control, in addition to the text displayed in the control. For example, you can display text for an item in the list control, such as "Item 1", and use the Value property to specify a value for that item, such as "$1.99".

You can have any combination of the inner HTML content, Text, or Value properties set. The resulting HTML output for the ListItem control depends on the combination of these three properties that are set. For example, if all three properties are set as follows:

<asp:ListItem Value = "Value 1" Text = "Item 1">Inner 1</asp:ListItem>

The inner HTML content is used for rendering the inner HTML content and the Value property is used for the Value attribute. The resulting HTML rendering output is:

<option value = "Value 1">Inner 1</option>

The following table lists the combination of set properties and the corresponding property used for the rendered inner HTML content and value attribute. The three columns on the left list the combination of set properties. The two columns on the right list which property value is used for the corresponding attribute.

Inner HTML Content	Text Property	Value Property	Rendered Inner HTML Content	Rendered Value Attribute
Set	Set	Set	Inner HTML Content	Value Property
Set	Set	Not Set	Inner HTML Content	Inner HTML Content
Set	Not Set	Set	Inner HTML Content	Value Property
Set	Not Set	Not Set	Inner HTML Content	Inner HTML Text
Not Set	Set	Set	Text Property	Value Property
Not Set	Set	Not Set	Text Property	Text Property
Not Set	Not Set	Set	Value Property	Value Property
Not Set	Not Set	Not Set	Not Set	Not Set

NOTE: Since the Text and Value properties have a default value of an empty string, it is possible to have empty list items in the list control.

When a list control is displayed, any ListItem control with its Selected property set to true appears highlighted in the control.

For a list of initial property values for an instance of ListItem, see the ListItem constructor.

The following example illustrates looping thru the collection of ListItem objects within a CheckBoxList control, to dynamically determine the selected items in the control.

 Show me 

ListControl   RadioButtonList   ListBox   DropDownList   CheckBoxList

Suggested Reading