Checkbox

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.

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. The glyph is hidden from screen readers - the checkbox already announces its own state - unless CheckIconAriaLabel names it, which is worth doing only where a custom icon says something the label does not.

LabelPosition places the label on any of the four sides of the box: End is the default reading order, Start puts it before the box - the usual layout when the BitCheckbox sits at the end of a settings row - and Top and Bottom stack it above or below, which is what dense toolbars and table headers need. Reversed is the single-flag shorthand for Start; the explicit parameter wins when both are set. Wherever the label sits, it stays part of the click target.

FullWidth stretches the BitCheckbox across its container and lets the label grow, which pushes the box to the far edge - the settings row. NoWrap keeps a label that no longer fits on one line and ends it with an ellipsis instead of wrapping; pair it with a Title so the part that was cut off is still reachable. Both panels below are the same width.

Description adds a second line under the label - the sentence that says what checking the box actually commits to. It is indented to line up with the label, sits outside the click target so selecting its text does not toggle the box, and is announced after the name of the checkbox. DescriptionTemplate replaces it with markup. For an explanation that should only be announced, use AriaDescription instead, shown in the Accessibility section.

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 display-only by default: the first click clears it and toggles the value, and only code can set it again, while DefaultIndeterminate merely starts it there in uncontrolled mode. Screen readers announce it as mixed.

The classic home of the 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.

ThreeState makes the mixed state 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. Two of the three steps move Value; the one out of indeterminate back to unchecked leaves it at false, so it is Indeterminate rather than Value that has to be watched to see every click.

Value: False, Indeterminate: False

A model that keeps all three answers in one bool? - yes, no and not answered - binds to the two parameters through a pair of one-line handlers, so the nullable stays the single source of truth:

subscribed: False

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:

LabelTemplate replaces the label with arbitrary markup - a formatted phrase, a tag, a link to the terms being agreed to - while the box, the toggle behavior and the click target all stay intact.

ChildContent goes one step further 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 - including the focus ring, which is drawn around the whole face once there is no box left to draw it around. The content is on its own to reflect the state, here by deriving the icon from the bound values.

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. OnFocus, OnFocusIn, OnFocusOut and OnBlur follow the focus. The checkbox below has all of them wired to a log - click it, or reach it with Tab, 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

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 - a templated label as well as a plain one. A read-only checkbox keeps the asterisk but drops the native attribute, which would otherwise refuse the submit over a box nobody is allowed to check; a disabled one drops both, since nothing is being asked of a control that is out of the interaction. Either way the requirement is still announced, through aria-required:

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.

AriaDescribedby points the checkbox at the element that holds the message, so the reason a submit was refused is read out with the control rather than only shown next to it.

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. Whatever its size, the click target is at least 24×24 CSS pixels, the minimum WCAG 2.2 asks of a pointer target. AutoFocus puts the initial focus on it when the page renders, and TabIndex moves it within the tab order.

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. When a visible element already labels it, AriaLabelledby points at that element instead of repeating the wording in an AriaLabel that could drift out of sync with it:

A disabled checkbox leaves the tab order, which hides it from anyone navigating by keyboard alone. AllowDisabledFocus keeps it reachable and announced as disabled instead, with its toggling suppressed either way - what a disabled command in a toolbar or a menu needs:

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:

AriaControls names the element a checkbox governs rather than merely labels - the list a select-all checkbox checks and clears - so assistive technologies can offer the way from the one to the other:

Loading turns the BitCheckbox busy: the glyph becomes a spinner, clicks are turned away and the checkbox is announced as busy, while it keeps the state it is in and stays focusable. It is what a checkbox that saves to a server on each toggle needs - the change is in flight, so it must not be started again.

AutoLoading raises that state by itself for as long as the awaited callbacks of a change are still running, so the usual case needs no flag of its own. Either way, a click landing while a change is still in flight is dropped rather than starting a competing one:

Saved: 0 time(s)

BitParams carries a BitCheckboxParams down to every checkbox under it, so a settings panel, a form, or a whole page sets the shared shape of its checkboxes once instead of on every one of them. What it carries is a default and not an override: a checkbox that writes a parameter for itself keeps its own value, and only what it left unset is filled in from the cascade, which is what lets one checkbox step out of the group it is in without the group having to know about it. Every parameter of the component is on the params object, and each of them is filled in on its own, so a checkbox can take its CheckIconName from the cascade and its Reversed from its own markup.

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.

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 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.

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, description, spinner, 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. Prefer Classes when your CSS should own states such as hover and focus, which inline styles cannot express.

Component's Style & Class:

Styles & Classes:

The checkbox also reads a set of CSS variables off its root for what no parameter covers. They inherit, so a value on :root or any ancestor re-skins every checkbox below it, and one on the Style of an instance re-skins that one alone. --bit-Checkbox-box-size is the one to reach for first: the glyph and the filled square of the mixed state are proportions of the box, so resizing the box carries the whole face with it.

CSS variables:

Set once on an ancestor, inherited by every checkbox inside it:

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.