CheckBox CheckBox CheckBox Class

Represents a control that a user can select (check) or clear (uncheck). A CheckBox can also report its value as indeterminate.

Syntax

Declaration

public class CheckBoxpublic class CheckBoxPublic Class CheckBox
<CheckBox .../>
-or-
<CheckBox>
  singleObject
</CheckBox>
-or-
<CheckBox>stringContent</CheckBox>

Inheritance Hierarchy

Inherited Members

Inherited properties

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited events

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited methods

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Remarks

CheckBox is a control that a user can select or clear.

The 3 states of a check box

Use the CheckBox control to provide a list of options that a user can select, such as a list of settings to apply to an application. Both CheckBox and RadioButton controls allow the user to select from a list of options. CheckBox controls allow the user to select a combination of options. In contrast, RadioButton controls allow the user to select from mutually exclusive options.

The CheckBox control inherits from ToggleButton and can have three states:

StatePropertyValue
checkedIsChecked true
uncheckedIsChecked false
indeterminateIsChecked null

For the CheckBox to report the indeterminate state, you must set the IsThreeState property to true.

Control style and template

You can modify the default Style and ControlTemplate to give the control a unique appearance. For information about modifying a control's style and template, see Styling controls. The default style, template, and resources that define the look of the control are included in the generic.xaml file. For design purposes, generic.xaml is available in the (Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP&lt;SDK version>\Generic folder from a Windows Software Development Kit (SDK) installation. Styles and resources from different versions of the SDK might have different values.

Starting in Windows 10, version 1607 (Windows Software Development Kit (SDK) version 10.0.14393.0), generic.xaml includes resources that you can use to modify the colors of a control in different visual states without modifying the control template. In apps that target this software development kit (SDK) or later, modifying these resources is preferred to setting properties such as Background and Foreground. For more info, see the Light-weight styling section of the Styling controls article.

This table shows the resources used by the CheckBox control.

Resource keyDescription
CheckBoxForegroundUncheckedLabel text color at rest and unchecked
CheckBoxForegroundUncheckedPointerOverLabel text color on hover and unchecked
CheckBoxForegroundUncheckedPressedLabel text color when pressed and unchecked
CheckBoxForegroundUncheckedDisabledLabel text color when disabled and unchecked
CheckBoxForegroundCheckedLabel text color at rest and checked
CheckBoxForegroundCheckedPointerOverLabel text color on hover and checked
CheckBoxForegroundCheckedPressedLabel text color when pressed and checked
CheckBoxForegroundCheckedDisabledLabel text color when disabled and checked
CheckBoxForegroundIndeterminateLabel text color at rest and indeterminate
CheckBoxForegroundIndeterminatePointerOverLabel text color on hover and indeterminate
CheckBoxForegroundIndeterminatePressedLabel text color when pressed and indeterminate
CheckBoxForegroundIndeterminateDisabledLabel text color when disabled and indeterminate
CheckBoxBackgroundUncheckedBackground color of entire control at rest and unchecked
CheckBoxBackgroundUncheckedPointerOverBackground color of entire control on hover and unchecked
CheckBoxBackgroundUncheckedPressedBackground color of entire control when pressed and unchecked
CheckBoxBackgroundUncheckedDisabledBackground color of entire control when disabled and unchecked
CheckBoxBackgroundCheckedBackground color of entire control at rest and checked
CheckBoxBackgroundCheckedPointerOverBackground color of entire control on hover and checked
CheckBoxBackgroundCheckedPressedBackground color of entire control when pressed and checked
CheckBoxBackgroundCheckedDisabledBackground color of entire control when disabled and checked
CheckBoxBackgroundIndeterminateBackground color of entire control at rest and indeterminate
CheckBoxBackgroundIndeterminatePointerOverBackground color of entire control on hover and indeterminate
CheckBoxBackgroundIndeterminatePressedBackground color of entire control when pressed and indeterminate
CheckBoxBackgroundIndeterminateDisabledBackground color of entire control when disabled and indeterminate
CheckBoxBorderBrushUncheckedBorder color of entire control at rest and unchecked
CheckBoxBorderBrushUncheckedPointerOverBorder color of entire control on hover and unchecked
CheckBoxBorderBrushUncheckedPressedBorder color of entire control when pressed and unchecked
CheckBoxBorderBrushUncheckedDisabledBorder color of entire control when disabled and unchecked
CheckBoxBorderBrushCheckedBorder color of entire control at rest and checked
CheckBoxBorderBrushCheckedPointerOverBorder color of entire control on hover and checked
CheckBoxBorderBrushCheckedPressedBorder color of entire control when pressed and checked
CheckBoxBorderBrushCheckedDisabledBorder color of entire control when disabled and checked
CheckBoxBorderBrushIndeterminateBorder color of entire control at rest and indeterminate
CheckBoxBorderBrushIndeterminatePointerOverBorder color of entire control on hover and indeterminate
CheckBoxBorderBrushIndeterminatePressedBorder color of entire control when pressed and indeterminate
CheckBoxBorderBrushIndeterminateDisabledBorder color of entire control when disabled and indeterminate
CheckBoxCheckBackgroundStrokeUncheckedBorder color of checkmark box at rest and unchecked
CheckBoxCheckBackgroundStrokeUncheckedPointerOverBorder color of checkmark box on hover and unchecked
CheckBoxCheckBackgroundStrokeUncheckedPressedBorder color of checkmark box when pressed and unchecked
CheckBoxCheckBackgroundStrokeUncheckedDisabledBorder color of checkmark box when disabled and unchecked
CheckBoxCheckBackgroundStrokeCheckedBorder color of checkmark box at rest and checked
CheckBoxCheckBackgroundStrokeCheckedPointerOverBorder color of checkmark box on hover and checked
CheckBoxCheckBackgroundStrokeCheckedPressedBorder color of checkmark box when pressed and checked
CheckBoxCheckBackgroundStrokeCheckedDisabledBorder color of checkmark box when disabled and checked
CheckBoxCheckBackgroundStrokeIndeterminateBorder color of checkmark box at rest and indeterminate
CheckBoxCheckBackgroundStrokeIndeterminatePointerOverBorder color of checkmark box on hover and indeterminate
CheckBoxCheckBackgroundStrokeIndeterminatePressedBorder color of checkmark box when pressed and indeterminate
CheckBoxCheckBackgroundStrokeIndeterminateDisabledBorder color of checkmark box when disabled and indeterminate
CheckBoxCheckBackgroundFillUncheckedBackground color of checkmark box at rest and unchecked
CheckBoxCheckBackgroundFillUncheckedPointerOverBackground color of checkmark box on hover and unchecked
CheckBoxCheckBackgroundFillUncheckedPressedBackground color of checkmark box when pressed and unchecked
CheckBoxCheckBackgroundFillUncheckedDisabledBackground color of checkmark box when disabled and unchecked
CheckBoxCheckBackgroundFillCheckedBackground color of checkmark box at rest and checked
CheckBoxCheckBackgroundFillCheckedPointerOverBackground color of checkmark box on hover and checked
CheckBoxCheckBackgroundFillCheckedPressedBackground color of checkmark box when pressed and checked
CheckBoxCheckBackgroundFillCheckedDisabledBackground color of checkmark box when disabled and checked
CheckBoxCheckBackgroundFillIndeterminateBackground color of checkmark box at rest and indeterminate
CheckBoxCheckBackgroundFillIndeterminatePointerOverBackground color of checkmark box on hover and indeterminate
CheckBoxCheckBackgroundFillIndeterminatePressedBackground color of checkmark box when pressed and indeterminate
CheckBoxCheckBackgroundFillIndeterminateDisabledBackground color of checkmark box when disabled and indeterminate
CheckBoxCheckGlyphForegroundUncheckedCheck mark color at rest and unchecked
CheckBoxCheckGlyphForegroundUncheckedPointerOverCheck mark color on hover and unchecked
CheckBoxCheckGlyphForegroundUncheckedPressedCheck mark color when pressed and unchecked
CheckBoxCheckGlyphForegroundUncheckedDisabledCheck mark color when disabled and unchecked
CheckBoxCheckGlyphForegroundCheckedCheck mark color at rest and checked
CheckBoxCheckGlyphForegroundCheckedPointerOverCheck mark color on hover and checked
CheckBoxCheckGlyphForegroundCheckedPressedCheck mark color when pressed and checked
CheckBoxCheckGlyphForegroundCheckedDisabledCheck mark color when disabled and checked
CheckBoxCheckGlyphForegroundIndeterminateCheck mark color at rest and indeterminate
CheckBoxCheckGlyphForegroundIndeterminatePointerOverCheck mark color on hover and indeterminate
CheckBoxCheckGlyphForegroundIndeterminatePressedCheck mark color when pressed and indeterminate
CheckBoxCheckGlyphForegroundIndeterminateDisabledCheck mark color when disabled and indeterminate

Examples

The following example shows two check box controls. The first check box demonstrates the checked and unchecked states. The second check box demonstrates the checked, unchecked, and indeterminate states. You can select the controls to change their appearance and see which state they are in.

<!-- A two-state CheckBox. -->
<CheckBox x:Name="cb1" Content="Two-state CheckBox"
          Checked="HandleCheck" Unchecked="HandleUnchecked" />
<TextBlock x:Name="text1"  />
    
<!-- A three-state CheckBox. -->
<CheckBox x:Name="cb2" Content="Three-state CheckBox" 
          IsThreeState="True" Indeterminate="HandleThirdState" 
          Checked="HandleCheck" Unchecked="HandleUnchecked" />
<TextBlock x:Name="text2"  />
private void HandleCheck(object sender, RoutedEventArgs e)
{
    CheckBox cb = sender as CheckBox;
    if (cb.Name == "cb1") text1.Text = "Two-state CheckBox checked.";
    else text2.Text = "Three-state CheckBox checked.";
}

private void HandleUnchecked(object sender, RoutedEventArgs e)
{
    CheckBox cb = sender as CheckBox;
    if (cb.Name == "cb1") text1.Text = "Two-state CheckBox unchecked.";
    else text2.Text = "Three-state CheckBox unchecked.";
}

private void HandleThirdState(object sender, RoutedEventArgs e)
{
    CheckBox cb = sender as CheckBox;
    text2.Text = "Three-state CheckBox indeterminate.";
}
Private Sub HandleCheck(ByVal sender As Object, ByVal e As RoutedEventArgs)
     Dim cb As CheckBox = CType(sender, CheckBox)
     If (cb.Name = "cb1") Then
         text1.Text = "Two state CheckBox checked."
     Else
         text2.Text = "Three state CheckBox checked."
     End If
 End Sub

 Private Sub HandleUnchecked(ByVal sender As Object, ByVal e As RoutedEventArgs)
     Dim cb As CheckBox = CType(sender, CheckBox)
     If (cb.Name = "cb1") Then
         text1.Text = "Two state CheckBox unchecked."
     Else
         text2.Text = "Three state CheckBox unchecked."
     End If
 End Sub

 Private Sub HandleThirdState(ByVal sender As Object, ByVal e As RoutedEventArgs)
     Dim cb As CheckBox = CType(sender, CheckBox)
     text2.Text = "Three state CheckBox indeterminate."
 End Sub

The 3 states of a check box

<StackPanel>
    <CheckBox x:Name="OptionsAllCheckBox" Content="Select all" IsThreeState="True" 
              Checked="SelectAll_Checked" Unchecked="SelectAll_Unchecked" Indeterminate="SelectAll_Indeterminate"/>
    <CheckBox x:Name="Option1CheckBox" Content="Option 1" Margin="24,0,0,0" 
              Checked="Option_Checked" Unchecked="Option_Unchecked"/>
    <CheckBox x:Name="Option2CheckBox" Content="Option 2" Margin="24,0,0,0" 
              Checked="Option_Checked" Unchecked="Option_Unchecked" IsChecked="True"/>
    <CheckBox x:Name="Option3CheckBox" Content="Option 3" Margin="24,0,0,0"
              Checked="Option_Checked" Unchecked="Option_Unchecked"/>
</StackPanel>
private void SelectAll_Checked(object sender, RoutedEventArgs e)
{
    Option1CheckBox.IsChecked = Option2CheckBox.IsChecked = Option3CheckBox.IsChecked = true;
}

private void SelectAll_Unchecked(object sender, RoutedEventArgs e)
{
    Option1CheckBox.IsChecked = Option2CheckBox.IsChecked = Option3CheckBox.IsChecked = false;
}

private void SelectAll_Indeterminate(object sender, RoutedEventArgs e)
{
    // If the SelectAll box is checked (all options are selected), 
    // clicking the box will change it to its indeterminate state.
    // Instead, we want to uncheck all the boxes,
    // so we do this programatically. The indeterminate state should
    // only be set programatically, not by the user.

    if (Option1CheckBox.IsChecked == true &&
        Option2CheckBox.IsChecked == true &&
        Option3CheckBox.IsChecked == true)
    {
        // This will cause SelectAll_Unchecked to be executed, so
        // we don't need to uncheck the other boxes here.
        OptionsAllCheckBox.IsChecked = false;
    }
}

private void SetCheckedState()
{
    // Controls are null the first time this is called, so we just 
    // need to perform a null check on any one of the controls.
    if (Option1CheckBox != null)
    {
        if (Option1CheckBox.IsChecked == true &&
            Option2CheckBox.IsChecked == true &&
            Option3CheckBox.IsChecked == true)
        {
            OptionsAllCheckBox.IsChecked = true;
        }
        else if (Option1CheckBox.IsChecked == false &&
            Option2CheckBox.IsChecked == false &&
            Option3CheckBox.IsChecked == false)
        {
            OptionsAllCheckBox.IsChecked = false;
        }
        else
        {
            // Set third state (indeterminate) by setting IsChecked to null.
            OptionsAllCheckBox.IsChecked = null;
        }
    }
}

private void Option_Checked(object sender, RoutedEventArgs e)
{
    SetCheckedState();
}

private void Option_Unchecked(object sender, RoutedEventArgs e)
{
    SetCheckedState();
} 

Constructors summary

Initializes a new instance of the CheckBox class.

Constructors

  • CheckBox()
    CheckBox()
    CheckBox()
    CheckBox()

    Initializes a new instance of the CheckBox class.

    public CheckBox()public New()Public Sub New()public CheckBox()

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll