# Checkbox
## Description
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.
## 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. |
| 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. |
| 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. |
| 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. |
## 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. |
| 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. |
## Enums
### 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. |
## Sub Classes
### 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. |
## Examples
\n**Basic**:
```razor
Label Template
```
\n**Indeterminate**:
```razor
Submit
```
```csharp
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() { }
```
\n**Custom content**:
```razor
Make Indeterminate
```
```csharp
private bool customCheckboxValue;
private bool customContentValue;
private bool customContentIndeterminate = true;
```
\n**Accessibility**:
```razor
Focus the checkbox
Value: @threeStateValue, Indeterminate: @threeStateIndeterminate
```
```csharp
private bool threeStateValue;
private bool threeStateIndeterminate;
```
\n**Binding**:
```razor
@(string.IsNullOrEmpty(eventsLog) ? "No clicks yet." : eventsLog)
Cancelled attempts: @cancelledCounter
Container clicks: @containerClickCounter
```
```csharp
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++;
}
```
\n**Read-only & Required**:
```razor