Checkbox
Accessible checkbox with helper text, disabled state, and Angular forms support.
- Selector
- ui-checkbox
- Package
- @ngnova/ui/checkbox
Import
import { UiCheckboxComponent } from '@ngnova/ui/checkbox';Usage & variants
Live examples use the public ui-checkbox API, paired with the exact snippet a product team would paste into an Angular app.
Subscription and bulk selection
Accessible checkbox with helper text, disabled state, and Angular forms support.
Reactive form boolean value.
Mixed child state.
Production guidance
Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.
When to use
Use for opt-in settings, agreement flags, independent preferences, and multi-select row controls.
Watch for
Indeterminate is visual and should be controlled by parent selection state.
Product recipes
Apply Checkbox in distinct, copyable product scenarios—not just an isolated component state.
Release checklist
Combine checked, mixed, and disabled states in one review workflow.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
<ui-checkbox
label="Email subscribers"
helperText="Reactive form boolean value."
[formControl]="newsletter"
/>
<ui-checkbox
label="Select all packages"
helperText="Mixed while only some packages are selected."
indeterminate
/>
<ui-checkbox
label="Security approval"
helperText="Unavailable until audit finishes."
disabled
/>Terms confirmation
Connect a required agreement to explanatory copy before allowing account creation.
1 2 3 4 5 6
<ui-checkbox
label="I agree to the workspace terms"
helperText="Required to create a shared workspace."
[formControl]="termsControl"
/>
<ui-button [disabled]="termsControl.invalid">Create workspace</ui-button>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
label '' string Visible checkbox label.
helperText '' string Support text shown below the label.
inputId generated string ID applied to the native checkbox.
name '' string Native input name.
ariaLabel '' string Accessible label when no visible label is provided.
disabled false boolean Disables the native checkbox.
required false boolean Marks the native checkbox as required.
indeterminate false boolean Shows the native mixed visual state until the user changes the value.
| Name | Type | Default | Description |
|---|---|---|---|
label | string | '' | Visible checkbox label. |
helperText | string | '' | Support text shown below the label. |
inputId | string | generated | ID applied to the native checkbox. |
name | string | '' | Native input name. |
ariaLabel | string | '' | Accessible label when no visible label is provided. |
disabled | boolean | false | Disables the native checkbox. |
required | boolean | false | Marks the native checkbox as required. |
indeterminate | boolean | false | Shows the native mixed visual state until the user changes the value. |
Outputs
valueChange OutputEmitterRef<boolean> Emits the checked value after user interaction.
indeterminateChange OutputEmitterRef<boolean> Supports two-way binding when the mixed state is cleared by user interaction.
focused OutputEmitterRef<FocusEvent> Emits when the native checkbox receives focus. The host also forwards a native focus event.
blurred OutputEmitterRef<FocusEvent> Emits when the native checkbox loses focus. The host also forwards a native blur event.
| Name | Type | Description |
|---|---|---|
valueChange | OutputEmitterRef<boolean> | Emits the checked value after user interaction. |
indeterminateChange | OutputEmitterRef<boolean> | Supports two-way binding when the mixed state is cleared by user interaction. |
focused | OutputEmitterRef<FocusEvent> | Emits when the native checkbox receives focus. The host also forwards a native focus event. |
blurred | OutputEmitterRef<FocusEvent> | Emits when the native checkbox loses focus. The host also forwards a native blur event. |
Accessibility
- Uses a native checkbox input.
- Helper text is associated with the control.
- When indeterminate is true, the native input exposes the mixed visual state and clears it after user interaction.
Keyboard behavior
- Space toggles the checkbox.
- Tab moves focus to the checkbox.
Testing guidance
- Assert CVA value, disabled state, indeterminateChange, focus, and blur outputs.