GET STARTED

Import

Both standalone contracts ship from the granular Checkbox entry point.

import {
  NeuralCheckbox,
  NeuralTriStateCheckbox,
  type NeuralTriStateCheckboxValue,
} from '@neural-ng/core/checkbox';

@Component({
  imports: [NeuralCheckbox, NeuralTriStateCheckbox],
})

Binary model

checked is always boolean. Projected text activates the real native checkbox through its wrapping label.

Tri-state model

The dedicated control cycles false → true → null → false. Null is the single authoritative mixed state.

States

Disabled, readonly, invalid and pending remain distinct so forms and assistive technology receive the correct contract.

Angular Forms

One native contract works with Signal Forms, Reactive Forms and template-driven forms without a legacy value accessor wrapper.

Semantic events

stateChange fires only for a user action and includes previous state plus the native event. Programmatic model writes remain silent.

Field composition

Inside Neural Field, Checkbox inherits control id, descriptions, required, invalid, pending, disabled, readonly, fluid and unstyled state.

<neural-field required invalid pending>
  <neural-checkbox>Marketing consent</neural-checkbox>
  <small neuralFieldHint>Choose your preference.</small>
  <small neuralFieldError>Consent is required.</small>
</neural-field>

Additive class ownership

Convenience classes and typed state slots merge with the theme layer; ordinary classes never erase the component appearance.

<neural-checkbox
  checkboxClass="max-w-md"
  inputClass="peer"
  labelClass="font-semibold"
  [classes]="{
    control: 'ring-offset-2',
    checkedControl: 'shadow-sm'
  }"
>
  Additive consumer classes
</neural-checkbox>

Unstyled and typed slots

The native input, projected label, state and structural hooks stay intact while all NeuralNg visual classes are removed.

Contract boundaries

Native semantics

Both controls render a real input[type=checkbox]. No synthetic checkbox role or keyboard emulation is required.

Accessible names

Prefer visible projected label text. Use ariaLabel only when the visual design has no text label.

Keyboard

Tab focuses the native input and Space changes its value. Readonly remains focusable but blocks mutation; disabled is removed from focus.

Mixed state

TriState maps null to the native indeterminate property and aria-checked="mixed". Binary Checkbox also accepts a presentation-only indeterminate input for collection controls while its model remains boolean.

Disabled versus readonly

Disabled prevents focus and native submission. Readonly is an accessible NeuralNg behavior that preserves focus and the current value.

Field state

Descriptions are joined through aria-describedby; invalid, required and pending map to their corresponding ARIA attributes.

Binary inputs

NeuralCheckbox implements FormCheckboxControl and accepts the shared inputs below.

Tri-state inputs

NeuralTriStateCheckbox implements FormValueControl<boolean | null>, accepts every shared input, and extends classes with mixedControl.

Models

Events

Methods

Typed class slots

Binary slots

Tri-state slots

Public types

Layout and typography

Color and state

Motion

Reduced-motion preferences collapse transitions automatically.