Checkbox

BitCheckbox turns a yes/no decision into a small clickable box with a label - check it to say yes, clear it to say no. It is backed by a real native checkbox input, so it is part of the tab order, toggles with Space, submits with forms and is announced correctly by screen readers. Beyond the two plain states it offers an indeterminate state for partially selected lists and an opt-in three-state cycle for questions whose honest third answer is no answer; each of the three states can render its own icon. The label can sit on any side of the box, changes can be cancelled before they land, and read-only and required modes plus form validation cover the form scenarios.

Usage


Basic

<BitCheckbox Label="Basic checkbox" />
<BitCheckbox Label="Checked by default" DefaultValue="true" />
<BitCheckbox Label="Hover over me" Title="The native tooltip of the checkbox" />
<BitCheckbox Label="Disable checkbox" IsEnabled="false" />
<BitCheckbox Label="Disable checked checkbox" IsEnabled="false" Value="true" />
A click anywhere on the BitCheckbox - the box or its label - toggles it. Left unbound like the first one below, it keeps its own state with no binding or event handler involved, and DefaultValue only picks where that state starts. Title fills the native tooltip shown on hover. Disabling the BitCheckbox greys it out and takes it out of the interaction; the disabled state renders both checked and unchecked.





Icons

<BitCheckbox Label="Custom check icon" CheckIconName="@BitIconName.Heart" />
<BitCheckbox Label="Custom unchecked icon" UncheckedIconName="@BitIconName.Cancel" />
<BitCheckbox Label="Custom indeterminate icon" Indeterminate IndeterminateIconName="@BitIconName.Remove" />
<BitCheckbox Label="Disabled custom check icon" CheckIconName="@BitIconName.WavingHand" Value="true" IsEnabled="false" />
Each state of the BitCheckbox can render its own icon: CheckIconName replaces the check mark of the checked state, UncheckedIconName puts an always-visible icon in the otherwise empty unchecked box - which by default only previews the check mark on hover - and IndeterminateIconName replaces the filled square of the indeterminate state. For icons from external libraries, the External Icons section shows the BitIconInfo counterparts of these parameters.




Reversed

<BitCheckbox Label="Reversed" Reversed />
<BitCheckbox Label="Reversed - Disabled" Reversed IsEnabled="false" />
<BitCheckbox Label="Reversed - Disable Checked" Reversed IsEnabled="false" Value="true" />
Reversed swaps the two sides, putting the label before the box - the usual layout when the BitCheckbox sits at the end of a settings row. It is the single-flag shorthand of the more general LabelPosition parameter demonstrated in the next section.



Label position

<BitCheckbox Label="End" LabelPosition="BitLabelPosition.End" />
<BitCheckbox Label="Start" LabelPosition="BitLabelPosition.Start" />
<BitCheckbox Label="Top" LabelPosition="BitLabelPosition.Top" />
<BitCheckbox Label="Bottom" LabelPosition="BitLabelPosition.Bottom" />
LabelPosition places the label on any of the four sides of the box: End is the default reading order, Start matches what Reversed does, and Top and Bottom stack the label above or below - handy in dense toolbars and table headers. Wherever the label sits, it stays part of the click target. It takes precedence over Reversed when both are set.

LabelTemplate

<BitCheckbox>
    <LabelTemplate>
        <BitTag Color="BitColor.Success">Label Template</BitTag>
    </LabelTemplate>
</BitCheckbox>
When a plain string is not enough - a formatted phrase, a tag, a link to the terms being agreed to - LabelTemplate replaces the label with arbitrary markup while the box, the toggle behavior and the click target all stay intact.

Indeterminate

<BitCheckbox Label="Indeterminate checkbox" Indeterminate />
<BitCheckbox Label="Indeterminate by default" DefaultIndeterminate="true" />
<BitCheckbox Label="Disabled indeterminate checkbox" Indeterminate IsEnabled="false" />


<BitCheckbox Label="Select all fruits"
             Value="selectAll"
             OnChange="HandleSelectAllChange"
             @bind-Indeterminate="selectAllIndeterminate" />
<BitCheckbox Label="Apple" Value="apple" OnChange="v => { apple = v; RefreshSelectAll(); }" />
<BitCheckbox Label="Banana" Value="banana" OnChange="v => { banana = v; RefreshSelectAll(); }" />
<BitCheckbox Label="Orange" Value="orange" OnChange="v => { orange = v; RefreshSelectAll(); }" />
@code {
    private bool apple;
    private bool banana;
    private bool orange;
    private bool selectAll;
    private bool selectAllIndeterminate;
    
    private void HandleSelectAllChange(bool value)
    {
        selectAll = value;
        selectAllIndeterminate = false;
        apple = banana = orange = value;
    }
    
    private void RefreshSelectAll()
    {
        var checkedCount = (apple ? 1 : 0) + (banana ? 1 : 0) + (orange ? 1 : 0);
    
        selectAll = checkedCount == 3;
        selectAllIndeterminate = checkedCount is > 0 and < 3;
    }
}
Indeterminate renders the third visual state - a filled square meaning "partially" - which takes visual precedence over the checked state without touching the underlying Value. It is a display-only state: the first click clears it and toggles the value, and only code can set it again (unless ThreeState makes it part of the cycle), while DefaultIndeterminate merely starts it there in uncontrolled mode. Screen readers announce it as mixed.






The classic home of the indeterminate state is a select-all checkbox that reflects a partially selected list: checked when every item is, unchecked when none is, and indeterminate in between.

Three-state

<BitCheckbox Label="Three-state checkbox" ThreeState
             @bind-Value="threeStateValue"
             @bind-Indeterminate="threeStateIndeterminate" />

<div>Value: <b>@threeStateValue</b>, Indeterminate: <b>@threeStateIndeterminate</b></div>
@code {
    private bool threeStateValue;
    private bool threeStateIndeterminate;
}
By default the indeterminate state is only reachable programmatically and the user can merely leave it. ThreeState makes it part of the interaction instead: each click cycles the BitCheckbox through unchecked, checked and indeterminate, for answers that are genuinely three-valued - yes, no, and no answer.


Value: False, Indeterminate: False

Binding

<BitCheckbox Label="One-way checked (Fixed)" Value="true" />

<BitCheckbox Label="One-way" Value="oneWayValue" />
<BitToggleButton @bind-IsChecked="oneWayValue" Text="Toggle" />

<BitCheckbox Label="Two-way controlled checkbox" @bind-Value="twoWayValue" />
<BitToggleButton @bind-IsChecked="twoWayValue" Text="Toggle" />


<BitCheckbox Label="One-way indeterminate (Fixed)" Indeterminate />

<BitCheckbox Label="One-way indeterminate" Indeterminate="oneWayIndeterminate" />
<BitToggleButton @bind-IsChecked="oneWayIndeterminate" Text="Toggle" />

<BitCheckbox Label="Two-way indeterminate" @bind-Indeterminate="twoWayIndeterminate" />
<BitToggleButton @bind-IsChecked="twoWayIndeterminate" Text="Toggle" />
@code {
    private bool oneWayValue;
    private bool twoWayValue;
    private bool oneWayIndeterminate = true;
    private bool twoWayIndeterminate = true;
}
Both Value and Indeterminate come in the usual binding shapes. Passed one-way, the parameter dictates the state: the BitCheckbox renders whatever the expression says and clicks cannot move it away from a fixed value. Bound two-way with @bind-Value or @bind-Indeterminate, changes flow in both directions - clicks update the field, and updating the field from elsewhere (the toggle buttons below) updates the BitCheckbox.


Value:







Indeterminate:



Events

<style>
    .clickable-box {
        padding: 1rem;
        cursor: pointer;
        border-radius: 0.25rem;
        border: 1px dashed gray;
    }
</style>

<BitCheckbox Label="Click me"
             OnClick="LogOnClick"
             OnChanging="LogOnChanging"
             OnChange="LogOnChange" />
<div>@(string.IsNullOrEmpty(eventsLog) ? "No clicks yet." : eventsLog)</div>


<BitCheckbox Label="Allow the change" @bind-Value="allowChange" />
<BitCheckbox Label="Guarded checkbox" OnChanging="HandleOnChanging" />
<div>Cancelled attempts: @cancelledCounter</div>


<div class="clickable-box" @onclick="() => containerClickCounter++">
    <BitCheckbox Label="Bubbles up" />
    <BitCheckbox Label="Stops here" StopPropagation />
</div>
<div>Container clicks: @containerClickCounter</div>
@code {
    private string eventsLog = string.Empty;
    private int cancelledCounter;
    private int containerClickCounter;
    private bool allowChange;
    
    private void LogOnClick() => eventsLog = "OnClick";
    
    private void LogOnChanging(BitCheckboxChangeArgs args) => eventsLog += $" → OnChanging({args.Value})";
    
    private void LogOnChange(bool value) => eventsLog += $" → OnChange({value})";
    
    private void HandleOnChanging(BitCheckboxChangeArgs args)
    {
        if (allowChange) return;
    
        args.Cancel = true;
        cancelledCounter++;
    }
}
Three callbacks fire in a fixed order around a click: OnClick first, while the state is still the old one; then OnChanging, carrying the state the BitCheckbox is about to move to; and finally OnChange, once the new state is committed. The checkbox below has all three wired to a log - click it and watch the order:


No clicks yet.



OnChanging is the veto point: setting Cancel on its arguments leaves the BitCheckbox where it was, so a change can be refused instead of silently reverted afterwards. It is awaited, so it can take its time - asking for confirmation, or checking with the server before letting the state through.



Cancelled attempts: 0



A BitCheckbox inside a clickable container fires that container's handler too - twice, in fact, since the label click and the click it forwards to the input both bubble. StopPropagation keeps the clicks to itself. Both checkboxes below sit in the same clickable box:


Container clicks: 0

Read-only & Required

<BitCheckbox Label="Read-only checkbox" ReadOnly @bind-Value="readOnlyValue" />
<BitToggleButton @bind-IsChecked="readOnlyValue" Text="Change it from here" />


<BitCheckbox Label="I accept the terms" Required />
@code {
    private bool readOnlyValue;
}
ReadOnly keeps the BitCheckbox focusable and lets screen readers announce it, but clicking or pressing Space no longer changes it - unlike disabling, which takes it out of the interaction entirely. The value can still change programmatically:




Required renders the native required attribute on the checkbox input and marks the label with an asterisk:

Validation

<style>
    .validation-message {
        color: red;
        font-size: 0.75rem;
    }
</style>

<EditForm Model="validationModel"
          OnValidSubmit="HandleValidSubmit"
          OnInvalidSubmit="HandleInvalidSubmit">
    <DataAnnotationsValidator />
    <BitCheckbox Label="I agree with the terms and conditions."
                 @bind-Value="validationModel.TermsAgreement" />
    <ValidationMessage For="@(() => validationModel.TermsAgreement)" />

    <BitButton ButtonType="BitButtonType.Submit">Submit</BitButton>
</EditForm>
@code {
    private BitCheckboxValidationModel validationModel = new();
    
    public class BitCheckboxValidationModel
    {
        [Range(typeof(bool), "true", "true", ErrorMessage = "You must agree to the terms and conditions.")]
        public bool TermsAgreement { get; set; }
    }
    
    private async Task HandleValidSubmit() { }
    
    private void HandleInvalidSubmit() { }
}
Inside an EditForm, the BitCheckbox takes part in validation like any other input: bind it to a model property, let data annotations state the rule - here, that the terms must be agreed to - and a failed submit shows the message. While invalid, the BitCheckbox also switches to its error styling and renders aria-invalid, so the failure is visible and announced right at the control.


Custom content

<BitCheckbox @bind-Value="customCheckboxValue">
    <BitIcon Style="border:1px solid gray;width:22px;height:22px"
             IconName="@(customCheckboxValue ? BitIconName.Accept : null)" />
    <span>Custom basic checkbox</span>
</BitCheckbox>


<BitCheckbox @bind-Value="customContentValue" @bind-Indeterminate="customContentIndeterminate">
    <BitIcon Style="border:1px solid gray;width:22px;height:22px"
             IconName="@(customContentIndeterminate ? BitIconName.Fingerprint : (customContentValue ? BitIconName.Accept : null))" />
    <span>Custom indeterminate checkbox</span>
</BitCheckbox>
<BitButton OnClick="() => customContentIndeterminate = true">Make Indeterminate</BitButton>
@code {
    private bool customCheckboxValue;
    private bool customContentValue;
    private bool customContentIndeterminate = true;
}
ChildContent goes one step beyond LabelTemplate and replaces the box and the label together: whatever markup you put inside the BitCheckbox becomes its face, while the clicking, the binding and the keyboard behavior keep working underneath. The content is on its own to reflect the state - here by deriving the icon from the bound values.


Accessibility

<BitCheckbox Label="Focus me with Tab, toggle me with Space" />


<BitButton OnClick="FocusTheCheckbox">Focus the checkbox</BitButton>
<BitCheckbox @ref="checkboxRef" Label="Programmatic focus target" />


<BitCheckbox AriaLabel="Select the row" />
<BitCheckbox Label="Auto renew" AriaDescription="The subscription will be renewed one day before it expires." />


<span id="newsletter-label">Weekly newsletter</span>
<BitCheckbox AriaLabelledby="newsletter-label" />


<BitCheckbox Label="Item 3" AriaSetSize="10" AriaPositionInSet="3" />
<BitCheckbox Label="Item 4" AriaSetSize="10" AriaPositionInSet="4" />
@code {
    private BitCheckbox checkboxRef = default!;
    
    private async Task FocusTheCheckbox() => await checkboxRef.FocusAsync();
}
The BitCheckbox is backed by a real, focusable checkbox input: Tab moves the focus to it - drawing a focus ring around the box - Space toggles it, and screen readers announce it as a checkbox, reading the indeterminate state as mixed. AutoFocus puts the initial focus on it when the page renders.




The FocusAsync method moves the focus programmatically:




A BitCheckbox without a visible label needs an AriaLabel to have an accessible name, and AriaDescription adds a visually hidden description that screen readers read after the name:

The subscription will be renewed one day before it expires.



When a visible element already labels the checkbox, AriaLabelledby points at it instead of repeating the wording in an AriaLabel that could drift out of sync with it:

Weekly newsletter



In a list that only shows a fragment of a larger set - a virtualized or paged list - AriaSetSize and AriaPositionInSet tell assistive technologies the real size of the set and where each checkbox sits in it:

Color

<BitCheckbox Color="BitColor.Primary" Label="Primary" />
<BitCheckbox Color="BitColor.Primary" Label="Primary" Indeterminate />
<BitCheckbox Color="BitColor.Primary" Label="Primary" Value />

<BitCheckbox Color="BitColor.Secondary" Label="Secondary" />
<BitCheckbox Color="BitColor.Secondary" Label="Secondary" Indeterminate />
<BitCheckbox Color="BitColor.Secondary" Label="Secondary" Value />

<BitCheckbox Color="BitColor.Tertiary" Label="Tertiary" />
<BitCheckbox Color="BitColor.Tertiary" Label="Tertiary" Indeterminate />
<BitCheckbox Color="BitColor.Tertiary" Label="Tertiary" Value />

<BitCheckbox Color="BitColor.Info" Label="Info" />
<BitCheckbox Color="BitColor.Info" Label="Info" Indeterminate />
<BitCheckbox Color="BitColor.Info" Label="Info" Value />

<BitCheckbox Color="BitColor.Success" Label="Success" />
<BitCheckbox Color="BitColor.Success" Label="Success" Indeterminate />
<BitCheckbox Color="BitColor.Success" Label="Success" Value />

<BitCheckbox Color="BitColor.Warning" Label="Warning" />
<BitCheckbox Color="BitColor.Warning" Label="Warning" Indeterminate />
<BitCheckbox Color="BitColor.Warning" Label="Warning" Value />

<BitCheckbox Color="BitColor.SevereWarning" Label="SevereWarning" />
<BitCheckbox Color="BitColor.SevereWarning" Label="SevereWarning" Indeterminate />
<BitCheckbox Color="BitColor.SevereWarning" Label="SevereWarning" Value />

<BitCheckbox Color="BitColor.Error" Label="Error" />
<BitCheckbox Color="BitColor.Error" Label="Error" Indeterminate />
<BitCheckbox Color="BitColor.Error" Label="Error" Value />

<BitCheckbox Color="BitColor.PrimaryBackground" Label="PrimaryBackground" />
<BitCheckbox Color="BitColor.PrimaryBackground" Label="PrimaryBackground" Indeterminate />
<BitCheckbox Color="BitColor.PrimaryBackground" Label="PrimaryBackground" Value />

<BitCheckbox Color="BitColor.SecondaryBackground" Label="SecondaryBackground" />
<BitCheckbox Color="BitColor.SecondaryBackground" Label="SecondaryBackground" Indeterminate />
<BitCheckbox Color="BitColor.SecondaryBackground" Label="SecondaryBackground" Value />

<BitCheckbox Color="BitColor.TertiaryBackground" Label="TertiaryBackground" />
<BitCheckbox Color="BitColor.TertiaryBackground" Label="TertiaryBackground" Indeterminate />
<BitCheckbox Color="BitColor.TertiaryBackground" Label="TertiaryBackground" Value />

<BitCheckbox Color="BitColor.PrimaryForeground" Label="PrimaryForeground" />
<BitCheckbox Color="BitColor.PrimaryForeground" Label="PrimaryForeground" Indeterminate />
<BitCheckbox Color="BitColor.PrimaryForeground" Label="PrimaryForeground" Value />

<BitCheckbox Color="BitColor.SecondaryForeground" Label="SecondaryForeground" />
<BitCheckbox Color="BitColor.SecondaryForeground" Label="SecondaryForeground" Indeterminate />
<BitCheckbox Color="BitColor.SecondaryForeground" Label="SecondaryForeground" Value />

<BitCheckbox Color="BitColor.TertiaryForeground" Label="TertiaryForeground" />
<BitCheckbox Color="BitColor.TertiaryForeground" Label="TertiaryForeground" Indeterminate />
<BitCheckbox Color="BitColor.TertiaryForeground" Label="TertiaryForeground" Value />

<BitCheckbox Color="BitColor.PrimaryBorder" Label="PrimaryBorder" />
<BitCheckbox Color="BitColor.PrimaryBorder" Label="PrimaryBorder" Indeterminate />
<BitCheckbox Color="BitColor.PrimaryBorder" Label="PrimaryBorder" Value />

<BitCheckbox Color="BitColor.SecondaryBorder" Label="SecondaryBorder" />
<BitCheckbox Color="BitColor.SecondaryBorder" Label="SecondaryBorder" Indeterminate />
<BitCheckbox Color="BitColor.SecondaryBorder" Label="SecondaryBorder" Value />

<BitCheckbox Color="BitColor.TertiaryBorder" Label="TertiaryBorder" />
<BitCheckbox Color="BitColor.TertiaryBorder" Label="TertiaryBorder" Indeterminate />
<BitCheckbox Color="BitColor.TertiaryBorder" Label="TertiaryBorder" Value />


<BitCheckbox IsEnabled="false" Color="BitColor.Primary" Label="Primary" />
<BitCheckbox IsEnabled="false" Color="BitColor.Primary" Label="Primary" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.Primary" Label="Primary" Value />

<BitCheckbox IsEnabled="false" Color="BitColor.Secondary" Label="Secondary" />
<BitCheckbox IsEnabled="false" Color="BitColor.Secondary" Label="Secondary" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.Secondary" Label="Secondary" Value />

<BitCheckbox IsEnabled="false" Color="BitColor.Tertiary" Label="Tertiary" />
<BitCheckbox IsEnabled="false" Color="BitColor.Tertiary" Label="Tertiary" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.Tertiary" Label="Tertiary" Value />

<BitCheckbox IsEnabled="false" Color="BitColor.Info" Label="Info" />
<BitCheckbox IsEnabled="false" Color="BitColor.Info" Label="Info" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.Info" Label="Info" Value />

<BitCheckbox IsEnabled="false" Color="BitColor.Success" Label="Success" />
<BitCheckbox IsEnabled="false" Color="BitColor.Success" Label="Success" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.Success" Label="Success" Value />

<BitCheckbox IsEnabled="false" Color="BitColor.Warning" Label="Warning" />
<BitCheckbox IsEnabled="false" Color="BitColor.Warning" Label="Warning" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.Warning" Label="Warning" Value />

<BitCheckbox IsEnabled="false" Color="BitColor.SevereWarning" Label="SevereWarning" />
<BitCheckbox IsEnabled="false" Color="BitColor.SevereWarning" Label="SevereWarning" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.SevereWarning" Label="SevereWarning" Value />

<BitCheckbox IsEnabled="false" Color="BitColor.Error" Label="Error" />
<BitCheckbox IsEnabled="false" Color="BitColor.Error" Label="Error" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.Error" Label="Error" Value />

<div style="background:var(--bit-clr-fg-sec);color:var(--bit-clr-bg-sec);padding:1rem">
    <BitCheckbox IsEnabled="false" Color="BitColor.PrimaryBackground" Label="PrimaryBackground" />
    <BitCheckbox IsEnabled="false" Color="BitColor.PrimaryBackground" Label="PrimaryBackground" Indeterminate />
    <BitCheckbox IsEnabled="false" Color="BitColor.PrimaryBackground" Label="PrimaryBackground" Value />

    <BitCheckbox IsEnabled="false" Color="BitColor.SecondaryBackground" Label="SecondaryBackground" />
    <BitCheckbox IsEnabled="false" Color="BitColor.SecondaryBackground" Label="SecondaryBackground" Indeterminate />
    <BitCheckbox IsEnabled="false" Color="BitColor.SecondaryBackground" Label="SecondaryBackground" Value />

    <BitCheckbox IsEnabled="false" Color="BitColor.TertiaryBackground" Label="TertiaryBackground" />
    <BitCheckbox IsEnabled="false" Color="BitColor.TertiaryBackground" Label="TertiaryBackground" Indeterminate />
    <BitCheckbox IsEnabled="false" Color="BitColor.TertiaryBackground" Label="TertiaryBackground" Value />
</div>

<BitCheckbox IsEnabled="false" Color="BitColor.PrimaryForeground" Label="PrimaryForeground" />
<BitCheckbox IsEnabled="false" Color="BitColor.PrimaryForeground" Label="PrimaryForeground" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.PrimaryForeground" Label="PrimaryForeground" Value />

<BitCheckbox IsEnabled="false" Color="BitColor.SecondaryForeground" Label="SecondaryForeground" />
<BitCheckbox IsEnabled="false" Color="BitColor.SecondaryForeground" Label="SecondaryForeground" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.SecondaryForeground" Label="SecondaryForeground" Value />

<BitCheckbox IsEnabled="false" Color="BitColor.TertiaryForeground" Label="TertiaryForeground" />
<BitCheckbox IsEnabled="false" Color="BitColor.TertiaryForeground" Label="TertiaryForeground" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.TertiaryForeground" Label="TertiaryForeground" Value />

<BitCheckbox IsEnabled="false" Color="BitColor.PrimaryBorder" Label="PrimaryBorder" />
<BitCheckbox IsEnabled="false" Color="BitColor.PrimaryBorder" Label="PrimaryBorder" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.PrimaryBorder" Label="PrimaryBorder" Value />

<BitCheckbox IsEnabled="false" Color="BitColor.SecondaryBorder" Label="SecondaryBorder" />
<BitCheckbox IsEnabled="false" Color="BitColor.SecondaryBorder" Label="SecondaryBorder" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.SecondaryBorder" Label="SecondaryBorder" Value />

<BitCheckbox IsEnabled="false" Color="BitColor.TertiaryBorder" Label="TertiaryBorder" />
<BitCheckbox IsEnabled="false" Color="BitColor.TertiaryBorder" Label="TertiaryBorder" Indeterminate />
<BitCheckbox IsEnabled="false" Color="BitColor.TertiaryBorder" Label="TertiaryBorder" Value />
Color picks the theme color the checked box and the indeterminate square fill with, with Primary as the default. The semantic colors - Success, Warning, Error and friends - tie the BitCheckbox to what agreeing to it means, while the Background, Foreground and Border families keep it legible on non-default surfaces like the inverted panel below. Each color is shown in all three states.





















Disabled:


















External Icons

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.1/css/all.min.css" />

<BitCheckbox Label="House (CheckIcon string)" CheckIcon="@("fa-solid fa-house")" />

<BitCheckbox Label="Heart (BitIconInfo.Css)" CheckIcon="@BitIconInfo.Css("fa-solid fa-heart")" Color="BitColor.Secondary" />

<BitCheckbox Label="Rocket (BitIconInfo.Fa)" CheckIcon="@BitIconInfo.Fa("solid rocket")" Color="BitColor.Error" />

<BitCheckbox Label="Minus (IndeterminateIcon)" Indeterminate IndeterminateIcon="@BitIconInfo.Fa("solid minus")" />


<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/font/bootstrap-icons.min.css" />

<BitCheckbox Label="House (CheckIcon string)" CheckIcon="@("bi bi-house-fill")" />

<BitCheckbox Label="Heart (BitIconInfo.Css)" CheckIcon="@BitIconInfo.Css("bi bi-heart-fill")" Color="BitColor.Secondary" />

<BitCheckbox Label="Gear (BitIconInfo.Bi)" CheckIcon="@BitIconInfo.Bi("gear-fill")" Color="BitColor.Error" />

<BitCheckbox Label="Square (UncheckedIcon)" UncheckedIcon="@BitIconInfo.Bi("app")" />
The per-state icons are not limited to the built-in icon font: CheckIcon, UncheckedIcon and IndeterminateIcon take a BitIconInfo - or a raw CSS class string - that can point at any icon library whose stylesheet is loaded, like FontAwesome or Bootstrap Icons below. Use BitIconInfo.Fa(), BitIconInfo.Bi() or BitIconInfo.Css() to build one.


FontAwesome:







Bootstrap Icons:




Size

<BitCheckbox Size="BitSize.Small" Label="Checkbox" />
<BitCheckbox Size="BitSize.Small" Label="Checkbox" Indeterminate />
<BitCheckbox Size="BitSize.Small" Label="Checkbox" Value />

<BitCheckbox Size="BitSize.Medium" Label="Checkbox" />
<BitCheckbox Size="BitSize.Medium" Label="Checkbox" Indeterminate />
<BitCheckbox Size="BitSize.Medium" Label="Checkbox" Value />

<BitCheckbox Size="BitSize.Large" Label="Checkbox" />
<BitCheckbox Size="BitSize.Large" Label="Checkbox" Indeterminate />
<BitCheckbox Size="BitSize.Large" Label="Checkbox" Value />
Size scales the box, its icon and the label together: Small for dense lists and table rows, Medium (the default) for forms, and Large where the BitCheckbox is a primary control or aimed at touch. Each size is shown in all three states.

Small:




Medium:




Large:

Style & Class

<style>
    .custom-class {
        padding: 0.5rem;
        border-radius: 0.125rem;
        background-color: #d3d3d347;
        border: 1px solid dodgerblue;
    }


    .custom-label {
        font-weight: bold;
        color: lightseagreen;
    }

    .custom-icon {
        color: lightseagreen
    }

    .custom-box {
        border-radius: 0.2rem;
        border-color: lightseagreen;
    }

    .custom-checked .custom-icon {
        color: white
    }

    .custom-checked:hover .custom-icon {
        color: whitesmoke;
    }

    .custom-checked .custom-box {
        background-color: lightseagreen;
    }

    .custom-checked:hover .custom-box {
        border-color: mediumseagreen;
    }
</style>


<BitCheckbox Label="Styled checkbox" Style="color: dodgerblue; text-shadow: lightskyblue 0 0 1rem;" />

<BitCheckbox Label="Classed checkbox" Class="custom-class" />


<BitCheckbox Label="Styles"
             Styles="@(new() { Checked = "--check-color: deeppink; --icon-color: white;",
                               Label = "color: var(--check-color);",
                               Box = "border-radius: 50%; border-color: var(--check-color); background-color: var(--check-color);",
                               Icon = "color: var(--icon-color);" })" />

<BitCheckbox Label="Classes"
             Classes="@(new() { Checked = "custom-checked",
                                Icon = "custom-icon",
                                Label="custom-label",
                                Box="custom-box" })" />
Style and Class land on the root element, which inline styles and a single class cover well. For anything deeper, Styles and Classes reach the individual parts - box, icon, label, container - and their Checked and Indeterminate entries apply only while the BitCheckbox is in that state, which is how the examples below restyle the checked look without touching the unchecked one.


Component's Style & Class:





Styles & Classes:


RTL

<BitCheckbox Dir="BitDir.Rtl" Label="چکباکس راست به چپ" />
<BitCheckbox Dir="BitDir.Rtl" Label="چکباکس غیرفعال" IsEnabled="false" />
<BitCheckbox Dir="BitDir.Rtl" Label="چکباکس غیرفعال چک شده" IsEnabled="false" Value="true" />
Setting Dir to BitDir.Rtl mirrors the whole layout for right-to-left languages: the box moves to the right of the label and the spacing follows, so the BitCheckbox reads naturally inside an RTL page like the Farsi examples below.



API

BitCheckbox parameters

Name Type Default value Description
AriaDescription string? null Detailed description of the checkbox for the benefit of screen readers, rendered as a visually hidden element that the checkbox input points to via aria-describedby.
AriaLabelledby string? null ID for element that contains label information for the checkbox.
AriaPositionInSet int? null The position in the parent set (if in a set) for aria-posinset.
AriaSetSize int? null The total size of the parent set (if in a set) for aria-setsize.
AutoFocus bool false If true, the checkbox input automatically receives focus when the page renders.
CheckIcon BitIconInfo? null The check icon using custom CSS classes for external icon libraries. Takes precedence over CheckIconName when both are set. Use BitIconInfo.Bi(), BitIconInfo.Fa(), or BitIconInfo.Css() for Bootstrap Icons, FontAwesome, or custom CSS.
CheckIconName string? Accept The name of the built-in icon to render as the check mark inside the checkbox.
CheckIconAriaLabel string? null The aria label of the icon for the benefit of screen readers.
ChildContent RenderFragment? null Used to customize the content of checkbox(Label and Box).
Classes BitCheckboxClassStyles? null Custom CSS classes for different parts of the BitCheckbox.
Color BitColor? null The general color of the checkbox.
DefaultIndeterminate bool? null Default indeterminate visual state for checkbox.
DefaultValue bool? null The default value of the checkbox to be used in uncontrolled mode (i.e. when the Value is not bound).
Indeterminate bool false An indeterminate visual state for checkbox. The indeterminate state takes visual precedence over the checked state but does not affect the Value.
IndeterminateIcon BitIconInfo? null The icon to render in the indeterminate state using custom CSS classes for external icon libraries, replacing the default filled square. Takes precedence over IndeterminateIconName when both are set.
IndeterminateIconName string? null The name of the built-in icon to render in the indeterminate state, replacing the default filled square.
Label string? null Descriptive label for the checkbox.
LabelPosition BitLabelPosition? null The position of the label in regards to the checkbox box. Takes precedence over Reversed when both are set.
LabelTemplate RenderFragment? null Used to customize the label for the checkbox.
Name string? null Name for the checkbox input. This is intended for use with forms and NOT displayed in the UI.
OnChange EventCallback<bool> Callback for when the checkbox value changes, once the new state is committed.
OnChanging EventCallback<BitCheckboxChangeArgs> Callback invoked before the state of the checkbox changes, letting the change be cancelled by setting Cancel on its arguments.
OnClick EventCallback<MouseEventArgs> Callback for when the checkbox clicked.
ReadOnly bool false Makes the checkbox read-only: it stays focusable and gets announced by screen readers, but user interaction no longer changes its state.
Required bool false Makes the checkbox required, rendering the native required attribute on its input and an asterisk next to its label.
Reversed bool false Reverses the label and checkbox location.
Size BitSize? null The size of the checkbox.
StopPropagation bool false If true, stops the click event from bubbling up to the parent elements.
Styles BitCheckboxClassStyles? null Custom CSS styles for different parts of the BitCheckbox.
ThreeState bool false Enables cycling through the unchecked, checked and indeterminate states on each click, instead of the indeterminate state being reachable only programmatically.
Title string? null Title text applied to the label container of the checkbox.
UncheckedIcon BitIconInfo? null The icon to render in the unchecked state using custom CSS classes for external icon libraries. Takes precedence over UncheckedIconName when both are set.
UncheckedIconName string? null The name of the built-in icon to render in the unchecked state. By default the unchecked box is empty and previews the check icon on hover.

BitInputBase parameters

Name Type Default value Description
DefaultValue TValue? null The default value of the input to be used in uncontrolled mode (i.e. when the Value is not bound), typically used alongside the OnChange callback.
DisplayName string? null Gets or sets the display name for this field.
InputHtmlAttributes IReadOnlyDictionary<string, object>? null Gets or sets a collection of additional attributes that will be applied to the created element.
Name string? null Gets or sets the name of the element. Allows access by name from the associated form.
NoValidate bool false Disables the validation of the input.
OnChange EventCallback<TValue?> Callback for when the input value changes.
ReadOnly bool false Makes the input read-only.
Required bool false Makes the input required.
Value TValue? null Gets or sets the value of the input. This should be used with two-way binding.

BitInputBase public members

Name Type Default value Description
InputElement ElementReference The ElementReference of the input element.
FocusAsync() () => ValueTask Gives focus to the input element.
FocusAsync(bool preventScroll) (bool preventScroll) => ValueTask Gives focus to the input element.

BitComponentBase parameters

Name Type Default value Description
AriaLabel string? null Gets or sets the accessible label for the component, used by assistive technologies.
Class string? null Gets or sets the CSS class name(s) to apply to the rendered element.
Dir BitDir? null Gets or sets the text directionality for the component's content.
ForceAnimation bool false Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested.
HtmlAttributes Dictionary<string, object> new Dictionary<string, object>() Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters.
Id string? null Gets or sets the unique identifier for the component's root element.
IsEnabled bool true Gets or sets a value indicating whether the component is enabled and can respond to user interaction.
Style string? null Gets or sets the CSS style string to apply to the rendered element.
TabIndex string? null Gets or sets the tab order index for the component when navigating with the keyboard.
Visibility BitVisibility BitVisibility.Visible Gets or sets the visibility state (visible, hidden, or collapsed) of the component.

BitComponentBase public members

Name Type Default value Description
UniqueId Guid Guid.NewGuid() Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed.
RootElement ElementReference Gets the reference to the root HTML element associated with this component.

BitCheckboxClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitCheckBox.
Container string? null Custom CSS classes/styles for the container of the BitCheckbox.
Checked string? null Custom CSS classes/styles for the checked state of the BitCheckbox.
Indeterminate string? null Custom CSS classes/styles for the indeterminate state of the BitCheckbox.
Box string? null Custom CSS classes/styles for the box element of the BitCheckbox.
Icon string? null Custom CSS classes/styles for the icon of the BitCheckbox.
Label string? null Custom CSS classes/styles for the label of the BitCheckbox.

BitCheckboxChangeArgs properties

The arguments of the OnChanging callback of the BitCheckbox.

Name Type Default value Description
Value bool false The checked state the checkbox is about to move to.
Indeterminate bool false The indeterminate state the checkbox is about to move to.
Cancel bool false Set to true to cancel the change and keep the current state of the checkbox.

BitColor enum

Name Value Description
Primary 0 Info Primary general color.
Secondary 1 Secondary general color.
Tertiary 2 Tertiary general color.
Info 3 Info general color.
Success 4 Success general color.
Warning 5 Warning general color.
SevereWarning 6 SevereWarning general color.
Error 7 Error general color.
PrimaryBackground 8 Primary background color.
SecondaryBackground 9 Secondary background color.
TertiaryBackground 10 Tertiary background color.
PrimaryForeground 11 Primary foreground color.
SecondaryForeground 12 Secondary foreground color.
TertiaryForeground 13 Tertiary foreground color.
PrimaryBorder 14 Primary border color.
SecondaryBorder 15 Secondary border color.
TertiaryBorder 16 Tertiary border color.

BitLabelPosition enum

Name Value Description
Top 0 The label shows on the top of the checkbox.
End 1 The label shows on the end of the checkbox.
Bottom 2 The label shows on the bottom of the checkbox.
Start 3 The label shows on the start of the checkbox.

BitSize enum

Name Value Description
Small 0 The small size checkbox.
Medium 1 The medium size checkbox.
Large 2 The large size checkbox.

BitVisibility enum

Name Value Description
Visible 0 The content of the component is visible.
Hidden 1 The content of the component is hidden, but the space it takes on the page remains (visibility:hidden).
Collapsed 2 The component is hidden (display:none).

BitDir enum

Name Value Description
Ltr 0 Ltr (left to right) is to be used for languages that are written from the left to the right (like English).
Rtl 1 Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic).
Auto 2 Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element.

Feedback

You can give us your feedback through our GitHub repo by filing a new Issue or starting a new Discussion.


Or you can review / edit this page on GitHub.


Or you can review / edit this component on GitHub.