CheckBox and CheckBoxList Web Server Controls Overview

  • Article

The CheckBox control and the CheckBoxList control provide a way for users to specify yes/no (true/false) choices.

This topic contains:

  • Features

  • Background

  • Code Examples

  • Class Reference

Features

You can use the CheckBox control and the CheckBoxList control to:

  • Cause a page postback when a check box is selected.

  • Capture user interaction when a user selects a check box.

  • Bind each check box to data from a database.

Back to top

Background

You can use two types of Web server controls to add check boxes to an ASP.NET Web page: individual CheckBox controls or a CheckBoxList control. Both controls provide a way for users to specify yes/no (true/false) choices.

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

Both types of controls have 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 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 data source. (You can bind an individual CheckBox control to data.)

Note

You can also use the HtmlInputCheckBox control to add check boxes to an ASP.NET Web page. For more information, see HtmlInputCheckBox Server Control Declarative Syntax.

CheckBox and CheckBoxList Events

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

CheckBox Control Events

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. However, you can force the control to perform an immediate postback by setting the AutoPostBack property to true. For more information, see How to: Respond to User Selection in a CheckBox Web Server Control.

Note

The auto-postback capability requires that the browser support ECMAScript (JScript, or JavaScript) and that scripting be enabled on the user's browser.

You might not need to create an event handler for the CheckedChanged event. You can test which check box is selected in any code that runs as part of the page. 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. For details, see How to: Set and Get the Selection in a RadioButton Web Server Control.

CheckBoxList Control Events

The CheckBoxList control raises a SelectedIndexChanged event when users select any check box in the list. By default, the event does not cause the page to be posted to the server. However, you can force the control to perform an immediate postback by setting the AutoPostBack property to true.

Note

The auto-postback capability requires that the browser support ECMAScript (JScript, or JavaScript) and that scripting be enabled on the user's browser.

As with individual CheckBox controls, it is more common to test the state of the CheckBoxList control after the page has been posted some other way. For details, see How to: Determine the Selection in List Web Server Controls.

CheckBox Control HTML Attributes

When the CheckBox control renders to the browser, it does so in two parts: an input element that represents the check box, and a separate label element that represents the caption for the check box. The combination of the two elements is 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. Therefore, it affects both the inner input and label attributes.

At times, you might want 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 lets you add HTML attributes to the input element, and the LabelAttributes property lets you add HTML attributes to label element. The attributes that you set are passed through as-is to the browser. The following example shows how to set attributes for the input element so that only the check box, but 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'");

Binding Data to the Controls

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, you typically set the control's Checked property based on 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.

Back to top

Code Examples

How to: Add CheckBox Web Server Controls to a Web Forms Page

How to: Add CheckBoxList Web Server Controls to a Web Forms Page

How to: Set Layout in a CheckBoxList Web Server Control

How to: Get and Set a CheckBox Web Server Control Value Programmatically

How to: Respond to User Selection in a CheckBox Web Server Control

How to: Add Items in List Web Server Controls

How to: Populate List Web Server Controls from a Data Source

How to: Respond to Changes in List Web Server Controls

Back to top

Class Reference

The following table lists the classes that relate to the CheckBox and CheckBoxList controls.

Member

Description

CheckBox

The main class for the CheckBox control.

CheckBoxList

The main class for the CheckBoxList control.

ListItem

The class that represents each item in CheckBoxList control.

Items

The collection of items that correspond to individual items in the list for a CheckBoxList control.

Back to top

See Also

Tasks

How to: Set the Selection in List Web Server Controls

How to: Determine the Selection in List Web Server Controls

Reference

RadioButton and RadioButtonList Web Server Controls Overview