Checkbox

Overview

Checkbox is a control that toggles between checked, unchecked, and indeterminate states. It can be controlled (@bind-Checked, a bool) or uncontrolled (DefaultChecked), and supports a tri-state value (@bind-CheckedState, a bool?, null = indeterminate). It renders a hidden bubble input so it participates in native form submission.

Anatomy

@using Navius.Primitives.Components.Checkbox

<NaviusCheckbox>
    <NaviusCheckboxIndicator />
</NaviusCheckbox>

Root

Renders a button with role="checkbox".

Prop	Type	Default	Description
Checked	bool	false	Controlled checked state. Pair with CheckedChanged (@bind-Checked).
CheckedChanged	EventCallback<bool>	-	Fires when the controlled Checked value should change.
DefaultChecked	bool	false	Initial checked state when used uncontrolled (boolean).
CheckedState	bool?	-	Controlled tri-state value: true = checked, false = unchecked, null = indeterminate. Pair with CheckedStateChanged (@bind-CheckedState). Takes precedence over Checked.
CheckedStateChanged	EventCallback<bool?>	-	Fires when the controlled CheckedState value should change.
DefaultCheckedState	bool?	-	Initial tri-state value for uncontrolled use (null = indeterminate).
Disabled	bool	false	Disables the checkbox.
ReadOnly	bool	false	Focusable but its value cannot be changed.
Required	bool	false	Marks the bubble input required for native form validation.
Parent	bool	false	Inside a NaviusCheckboxGroup, marks this as the select-all parent: it rolls up to checked/unchecked/indeterminate over the group’s AllValues and toggles them all. Ignored outside a group.
Name	string?	-	Form field name. In a group this is the checkbox’s identity; standalone it also renders a hidden bubble input.
Value	string	"on"	Submitted form value when checked.
ChildContent	RenderFragment?	-	The checkbox’s indicator.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered button.

Indicator

Renders when the checkbox is in a checked or indeterminate state. Renders a span.

Prop	Type	Default	Description
KeepMounted	bool	false	Keeps the indicator mounted even when unchecked.
ChildContent	RenderFragment?	-	Indicator content (e.g. a check glyph).
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered span.

Data attributes

Part	Attribute	Description
Root	data-checked	Present when checked.
Root	data-unchecked	Present when unchecked.
Root	data-indeterminate	Present when indeterminate.
Root	data-disabled	Present when disabled.
Root	data-readonly	Present when read-only.
Root	data-required	Present when required.
Indicator	data-checked	Present when checked.
Indicator	data-unchecked	Present when unchecked.
Indicator	data-indeterminate	Present when indeterminate.
Indicator	data-disabled	Present when disabled.
Indicator	data-readonly	Present when read-only.
Indicator	data-required	Present when required.

Keyboard interactions

Key	Behavior
Space	Toggles the component’s state.

ARIA mechanism

The Root wires role="checkbox" with the correct aria-checked state (including "mixed" for indeterminate), plus aria-readonly and aria-required when set. This implements the roles, states, and keyboard map of the WAI-ARIA APG tri-state checkbox pattern and is covered by the Playwright browser test suite and gated by axe-core in CI.