CheckBox and CheckBoxList Web Server Controls Overview

Article
10/15/2014

You can use two types of Web server controls to add check boxes to a Web Forms page: individual CheckBox controls or a CheckBoxList control. Both controls provide a way for users to input Boolean data: true or false, yes or no.

Note
You can also use the HtmlInputCheckBox control to add check boxes to a Web Forms page. For more information, see HtmlInputCheckBox Server Control Declarative Syntax.

CheckBox Control versus CheckBoxList Control

You add individual CheckBox controls to a page and work with them singly. Alternatively, the CheckBoxList control is a single control that acts as a parent control for a collection of check-box list items. It derives from a base ListControl class, and therefore works much like the ListBox, DropDownList, RadioButtonList, and BulletedList Web server controls. For that reason, many of the procedures for working with the CheckBoxList control are the same as the procedures for the other list Web server controls.

Each type of control has advantages. By using individual CheckBox controls, you get more control over the layout of the check boxes on the page than by using the CheckBoxList control. For example, you can include text (that is, non-check-box text) between each check box. You can also control the font and color of individual check boxes.

The CheckBoxList control is a better choice if you want to create a series of check boxes from data in a database. (You can still bind an individual CheckBox control to data.)

CheckBox Events

Events work differently between individual CheckBox controls and the CheckBoxList control.

Individual CheckBox Controls

Individual CheckBox controls raise the CheckedChanged event when users click the control. By default, this event does not cause the page to be posted to the server, but you can have the control force an immediate post by setting the AutoPostBack property to true. For details about responding to this event directly, see How to: Respond to User Selection in a CheckBox Web Server Control.

Note
The ability of a CheckBox control to post to the server when it is checked requires that the browser support ECMAScript (JavaScript) and that scripting be enabled on the user's browser.

Whether a CheckBox control posts to the server or not, you might not need to create an event handler for the CheckedChanged event. You can test which check box is selected in the handler. Typically, you create an event handler for the CheckedChanged event only if you need to know that the check box was changed, not just to read the value of a check box.

CheckBox Control HTML Attributes

When the CheckBox control renders to the browser, it does so in two parts: an input element representing the check box, and a separate label element representing the caption for the check box. The combination of the two elements is in turn wrapped in a span element.

When you apply style or attribute settings to a CheckBox control, the settings are applied to the outer span element. For example, if you set the control's BackColor property, the setting is applied to the span element, and therefore it affects both the inner input and label attributes.

At times, you might want to be able to apply separate settings to the check box and to the label. The CheckBox control supports two properties that you can set at run time: the InputAttributes property and the LabelAttributes property. Each property allows you to add HTML attributes to the input and label elements, respectively. The attributes that you set are passed through as-is to the browser. For example, the following code example shows how to set attributes for the input element so that only the check box, not the label, changes color when users pass the mouse pointer over it.

[Visual Basic]

CheckBox1.InputAttributes.Add("onmouseover", _
    "this.style.backgroundColor = 'red'")
CheckBox1.InputAttributes.Add("onmouseout", _
    "this.style.backgroundColor = 'white'")
CheckBox1.InputAttributes.Add("onmouseover", 
    "this.style.backgroundColor = 'red'");
CheckBox1.InputAttributes.Add("onmouseout", 
    "this.style.backgroundColor = 'white'");

CheckBoxList Control

In contrast, the CheckBoxList control raises a SelectedIndexChanged event when users select any check box in the list. By default, the event does not cause the form to be posted to the server, although you can specify this option by setting the AutoPostBack property to true.

As with individual CheckBox controls, it is more common to test the state of the CheckBoxList control after the form has been posted some other way.

Binding Data to the Control

As with any Web server control, you can bind an individual CheckBox control to a data source, and you can bind any property of the CheckBox control to any field of the data source. For example, it is typical to set the control's Checked property from information in a database.

You can also bind a CheckBoxList control to a data source. In that case, the check boxes each represent a different record in the data source.