Forms

Stable - @kikita-labs/ui v2.0.0

Checkbox

Native checkbox styling with field ARIA wiring and invalid state integration.

Import

Use the directive on native checkbox inputs and pair it with kui-field for label, hint, and error wiring.

checkbox.ts
import { KuiCheckbox, KuiField } from '@kikita-labs/ui';

Usage

Open in Playground

Keep a native label around the checkbox for option text.

Control product and release emails

<kui-field label="Notifications" hint="Control product and release emails">
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" [checked]="receiveUpdates()" />
    <span>Receive updates</span>
  </label>
</kui-field>

Sizes and states

Match checkbox size to surrounding field density and text scale; disabled and invalid follow native and field-driven state.

<div class="checkbox-size-example">
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" size="xs" />
    <span>Extra small</span>
  </label>
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" size="sm" checked />
    <span>Small</span>
  </label>
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" size="md" checked />
    <span>Medium</span>
  </label>
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" size="lg" />
    <span>Large</span>
  </label>
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" disabled />
    <span>Disabled</span>
  </label>
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" disabled checked />
    <span>Disabled and checked</span>
  </label>
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" invalid />
    <span>Invalid</span>
  </label>
</div>

Signal Forms

Bind Angular Signal Forms with [formField] on the same native checkbox; the field gates the invalid state until the control is touched and exposes aria-required.

settings.html
<kui-field label="Notifications" hint="Control product and release emails">
  <label>
    <input kuiCheckbox type="checkbox" [formField]="settingsForm.receiveUpdates" />
    Receive updates
  </label>
</kui-field>

For custom checkbox-like components prefer the Angular Signal Forms FormCheckboxControl contract over a ControlValueAccessor.

Provider defaults

Set defaults.checkbox once for the application or for a subtree. Each option resolves as local input > defaults.checkbox.<option> > built-in default.

import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        checkbox: {
          /* options below */
        },
      },
    }),
  ],
};
NameTypeDefaultDescription
size'xs' | 'sm' | 'md' | 'lg' — Component size. Takes precedence over the global defaults.size.

API

Inputs verified against @kikita-labs/ui v2.0.0 public typings.

NameTypeDefaultDescription
size'xs' | 'sm' | 'md' | 'lg''md'Checkbox size mapped to Kikita checkbox tokens.
invalidbooleanfalseMarks the checkbox invalid outside a field error state.
idstring | undefined-Explicit id override. Inside kui-field, the field id is used when omitted.
checkedbooleanfalseNative checked state. Not a directive input; bind it directly on the input element.
disabledbooleanfalseNative disabled state. Not a directive input; bind it directly on the input element.
indeterminatebooleanfalseNative DOM property, not an HTML attribute or directive input. Set it imperatively on the element to show the dash-mark state; .kui-checkbox styles :indeterminate.

Accessibility

Checkbox keeps native input semantics and adds field-described state when used inside kui-field.

  • Use a native label for the checkbox option text.
  • Use kui-field for group label, hint, error, and described-by wiring.
  • Use native checked and disabled states; do not replace the input with a custom role.
  • Use invalid only when the checkbox is outside a field error state.
  • Inside kui-field the control receives the field id and aria-describedby, and an explicit required on the field or a Signal Forms required(...) validator is exposed as aria-required.
  • Focus is a solid 2px outline in --kui-color-focus. Disabled checkboxes dim to the shared 0.5 opacity, and checked and indeterminate states keep system colours in forced colors mode.
  • .kui-checkbox styles the native :indeterminate pseudo-class (a dash mark instead of a checkmark). indeterminate is a DOM property, not an HTML attribute, so set it imperatively on the element.

Migrating to 2.0

Consumer-visible changes of @kikita-labs/ui 2.0 for Checkbox.

  • The class is KuiCheckbox (it was KuiCheckboxDirective); the selector and inputs are unchanged. ng update @kikita-labs/ui renames the import.
  • The size comes from the parent field, then defaults.checkbox.size, then the global defaults.size.
  • The control reads its host id, invalid state and aria-describedby from one internal helper and, inside kui-field, no longer pulls the whole field into your bundle.
  • The focus ring is a 2px outline, disabled controls dim to the shared 0.5 opacity, and checked and indeterminate states have forced-colors styling.