Component v1.1.0 Forms

Checkbox

Accessible checkbox with helper text, disabled state, and Angular forms support.

API Stable 2.1 WCAG notes Ready Dark mode
Selector
ui-checkbox
Package
@ngnova/ui/checkbox

Import

Standalone Tailwind v4
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.

API Reference

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.

Angular template ui-checkbox-recipe.example.html
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.

Angular template ui-checkbox-recipe.example.html
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.

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.

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.