Share via


CheckBoxList Web Server Control

Creates a multiselection check box group. This control supports binding to a data source.

<asp:CheckBoxList id="CheckBoxList1"
     AutoPostBack="True|False"
     CellPadding="Pixels"
     DataSource='<% databindingexpression %>'
     DataTextField="DataSourceField"
     DataValueField="DataSourceField"
     RepeatColumns="ColumnCount"
     RepeatDirection="Vertical|Horizontal"
     RepeatLayout="Flow|Table"
     TextAlign="Right|Left"
     OnSelectedIndexChanged="OnSelectedIndexChangedMethod"
     runat="server">

   <asp:ListItem value="value" 
        selected="True|False">
      Text
   </asp:ListItem>

</asp:CheckBoxList>

Remarks

The CheckBoxList control creates a multiselection check box group that can be dynamically generated using data binding. To specify items that you want to appear in the CheckBoxList control, place a ListItem element for each entry between the opening and closing tags of the CheckBoxList control.

Note   You can also use multiple CheckBox controls. The CheckBoxList control is easier for creating a set of check boxes using data binding, while the individual CheckBox control gives you greater control over layout.

The CheckBoxList control also supports data binding. To bind the control to a data source, first create a data source, such as a System.Collections.ArrayList object, that contains the items to display in the control. Next, use the Control.DataBind method to bind the data source to the CheckBoxList control. Use the DataTextField and DataValueField properties to specify which field in the data source to bind to the Text and Value properties of each list item in the control, respectively. The CheckBoxList control will now display the information from the data source.

To determine the selected items in the CheckBoxList control, iterate through the Items collection and test the Selected property of each item in the collection.

You can specify the way the list is displayed by using the RepeatLayout and RepeatDirection properties. If RepeatLayout is set to RepeatLayout.Table (the default setting), the list is rendered within a table. If it is set to RepeatLayout.Flow, the list is rendered without any table structure. By default, RepeatDirection is set to RepeatDirection.Vertical. Setting this property to RepeatDirection.Horizontal renders the list horizontally.

CAUTION   Text is not HTML encoded before it is displayed in the CheckBoxList control. This makes it possible to embed script within HTML tags in the text. If the values for the control come from user input, be sure to validate the values to help prevent security vulnerabilities.

For detailed information on the CheckBoxList Web server control's properties and events, see the CheckBoxList Class documentation.

Example

The following shows a sample declaration for a CheckBoxList control in an .aspx file. The list contains six items that are not mutually exclusive. When a user checks one of the boxes, the page is not immediately posted back to the server (the page is not posted until some other event occurs, such as a Button click). No OnSelectedIndexChanged event handler is called because no method is declared for that event.

<asp:CheckBoxList id="Check1"
     RepeatLayout="flow"
     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:CheckBoxList>

The following example shows how you can determine the selected check boxes in a CheckBoxList control. The code iterates through the control's Items collection and tests each item's Selected property. The selected items are then displayed in the Label control.

Sub Button1_OnClick(sender As Object, e As EventArgs)
   Dim s As String
   Dim i As Integer
   s = "Selected items:<br>"
   For i=0 to Check1.Items.Count - 1
      If Check1.Items(i).Selected Then
         s = s & Check1.Items[i].Text & "<br>"
      End If 
   Next i
   Label1.Text = s
End Sub
[C#]
void Button1_OnClick(Object sender, EventArgs e)
{
   string s;
   s = "Selected items:<br>";
   for (int i=0; i < Check1.Items.Count; i++)
   {
      if ( Check1.Items[i].Selected )
      {
         s = s + Check1.Items[i].Text + "<br>";
      }
   }
   Label1.Text = s;
}

See Also

Web Server Controls | CheckBoxList Class