Class SfCheckBox<TChecked>

Represents a configurable CheckBox component which allows the user to select, deselect, or display an indeterminate state. This component supports checked, unchecked, and indeterminate states, and can be used in forms or as a standalone UI input to collect binary or triple-state responses.

Inheritance
System.Object
SfBaseComponent
SfSelectionBase<TChecked>
SfCheckBox<TChecked>
Implements
System.IAsyncDisposable
Inherited Members
Syncfusion.Blazor.Toolkit.Inputs.SfSelectionBase<TChecked>.CheckedChanged
Syncfusion.Blazor.Toolkit.Inputs.SfSelectionBase<TChecked>.CheckedExpression
Syncfusion.Blazor.Toolkit.Inputs.SfSelectionBase<TChecked>.ChildContent
Syncfusion.Blazor.Toolkit.Inputs.SfSelectionBase<TChecked>.HtmlAttributes
Namespace: Syncfusion.Blazor.Toolkit.Inputs
Assembly: Syncfusion.Blazor.Toolkit.dll
Syntax
public class SfCheckBox<TChecked> : SfSelectionBase<TChecked>, IAsyncDisposable
Type Parameters
Name Description
TChecked

The type of the checked value. Supported types: bool, bool?, byte, byte?
Remarks

The SfCheckBox<TChecked> component supports checked, unchecked, and indeterminate states. It provides support for two-state and tristate selection patterns with flexible property configuration, including custom label positioning, enable/disable tri-state, RTL support, and accessibility options.

The checkbox state can be two or three states based on the EnableTriState property and is intended for both standalone use and within forms.

Supported generic types for TChecked: bool, bool?, byte, byte?.

Examples

Basic checkbox that is initially checked:

<SfCheckBox @bind-Checked="isAccepted" Label="I accept the terms" />

@code {
private bool isAccepted = true;
}

Tristate checkbox with indeterminate state:

<SfCheckBox @bind-Checked="selectAll" 
            EnableTriState="true" 
            Label="Select All"
            ValueChange="OnSelectAllChanged" />

@code {
private bool? selectAll = null;


private void OnSelectAllChanged(CheckedChangeEventArgs &lt;bool?> args)
{
    // Handle the state change
}



}

Constructors

SfCheckBox()

Declaration
public SfCheckBox()

Properties

EnableTriState

Gets or sets a value indicating whether the checkbox supports three-state mode (checked, unchecked, and indeterminate).

Declaration
public bool EnableTriState { get; set; }
Property Value
Type Description
System.Boolean

true if tri-state mode is enabled; otherwise, false. The default value is false.
Remarks

When enabled, the checkbox cycles through three states when clicked:

  1. Checked
  2. Indeterminate
  3. Unchecked

Tri-state mode is particularly useful for "Select All" scenarios in hierarchical lists or when representing partial selections.

To support tri-state functionality, use a nullable boolean type for TChecked (e.g., bool?).

Examples

Tri-state checkbox with nullable boolean:

<SfCheckBox TChecked="bool?"
            @bind-Checked="triStateValue"
            EnableTriState="true"
            Label="Select All Items" />

@code {
private bool? triStateValue = null; // null = indeterminate
}

Indeterminate

Gets or sets a value indicating whether the checkbox is in the indeterminate (mixed) state.

Declaration
public bool Indeterminate { get; set; }
Property Value
Type Description
System.Boolean

true if the checkbox is in the indeterminate state; otherwise, false. The default value is false.
Remarks

The indeterminate state represents a "mixed" or "partially checked" state, typically used in hierarchical scenarios where some but not all child items are selected.

Setting Indeterminate to true visually displays the checkbox in the indeterminate state and sets the aria-checked attribute to "mixed" for accessibility.

When the user clicks an indeterminate checkbox, it transitions based on the EnableTriState setting.

Examples

Hierarchical checkbox scenario:

<SfCheckBox @bind-Checked="selectAll" 
            @bind-Indeterminate="isPartiallySelected"
            Label="Select All"
            ValueChange="OnParentChanged" />

@code {
private bool? selectAll;
private bool isPartiallySelected;


private void OnParentChanged(ChangeEventArgs&lt;bool?> args)
{
    // Handle parent checkbox state change
}



}

Label

Gets or sets the label text displayed next to the checkbox.

Declaration
public string Label { get; set; }
Property Value
Type Description
System.String

A System.String representing the label content for the checkbox. The default value is System.String.Empty.
Remarks

This property specifies the descriptive text shown beside the checkbox element. Use this to provide clear context about what the checkbox represents.

Examples
<SfCheckBox Label="Accept Terms and Conditions" @bind-Checked="acceptedTerms" />

@code {
    private bool acceptedTerms;
}

LabelPosition

Gets or sets the position of the label relative to the checkbox.

Declaration
public LabelPosition LabelPosition { get; set; }
Property Value
Type Description
LabelPosition

One of the LabelPosition enumeration values: Before or After. The default value is Before.
Remarks

Before: The label appears to the left of the checkbox (in LTR layouts).

After: The label appears to the right of the checkbox (in LTR layouts).

Examples
<SfCheckBox Label="I agree to the terms" 
            LabelPosition="LabelPosition.After"
            @bind-Checked="agreed" />

@code {
    private bool agreed;
}

Logger

Gets or sets the logger used for capturing diagnostic and runtime information related to the SfCheckBox<TChecked> component.

Declaration
public ILogger<SfCheckBox<TChecked>> Logger { get; set; }
Property Value
Type
Microsoft.Extensions.Logging.ILogger<SfCheckBox<TChecked>>
Remarks

This logger is primarily intended for internal use to record trace, debug, warning, and error information during component execution.

ValueChange

Gets or sets an event callback that is invoked when the checkbox state changes due to user interaction.

Declaration
public EventCallback<CheckedChangeEventArgs<TChecked>> ValueChange { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<CheckedChangeEventArgs<TChecked>>

An Microsoft.AspNetCore.Components.EventCallback<> of ChangeEventArgs<T> that is triggered when the checkbox state is changed by the user. The callback argument contains the updated checked state and the mouse event details.
Remarks

This event is raised only from UI-based interactions (such as mouse or touch clicks), not from programmatic changes to the Checked property.

Use this event to react to state changes for:

  • Form validation
  • Conditional logic based on checkbox state
  • Synchronizing with other UI elements
  • Analytics or logging

For two-way data binding without custom logic, use @bind-Checked instead.

Examples

Basic value change handling:

<SfCheckBox Label="Accept Terms"
            @bind-Checked="acceptedTerms"
            ValueChange="OnTermsChanged" />

@code {
private bool acceptedTerms;


private void OnTermsChanged(CheckedChangeEventArgs&lt;bool> args)
{
    Console.WriteLine($&quot;Checkbox changed to: {args.Checked}&quot;);

    // Perform validation or other logic
    if (args.Checked)
    {
        // User accepted terms
    }
}



}

Tri-state checkbox with value change:

<SfCheckBox TChecked="bool?"
            @bind-Checked="selectAll"
            EnableTriState="true"
            Label="Select All"
            ValueChange="OnSelectAllChanged" />

@code {
private bool? selectAll;


private void OnSelectAllChanged(CheckedChangeEventArgs&lt;bool?> args)
{
    if (args.Checked == true)
    {
        // Select all items
    }
    else if (args.Checked == false)
    {
        // Deselect all items
    }
    else
    {
        // Indeterminate state (null)
    }
}



}

Methods

BuildRenderTree(RenderTreeBuilder)

Declaration
protected override void BuildRenderTree(RenderTreeBuilder __builder)
Parameters
Type Name Description
Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder __builder

Implements

System.IAsyncDisposable