FORMSBETA

Checkbox

Native binary and tri-state controls with separate type-safe models, complete Angular Forms support and consumer-owned visuals.

Native inputSignal Forms readyMixed state

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.

I accept the terms

Not accepted

Tri-state model

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

Inherit workspace permission

Value: null (mixed)

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.

SIGNAL FORMS

Product updates

true

REACTIVE FORMS

Security alerts

false

NGMODEL

Weekly digest

true

Semantic events

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

Emit binary event

Emit tri-state event

No user action yet.

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.

Consumer-owned checkbox

checked: false

Contract boundaries

Binary

Owns boolean checked state.

Tri-state

Owns boolean or null value.

Application

Owns business validation and persistence.

ACCESSIBILITY

Native behavior first

Checkbox retains browser focus, label activation, validation, form submission and keyboard behavior.

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.

PUBLIC API

Checkbox contracts

Canonical symbols are NeuralCheckbox and NeuralTriStateCheckbox. Their value models remain deliberately separate.

Binary inputs

NeuralCheckbox implements FormCheckboxControl and accepts the shared inputs below.

Input	Type	Default	Purpose
indeterminate (NeuralCheckbox)	boolean	false	Presentation-only mixed state for partial collection selection.
disabled	boolean	false	Disables the native input and removes interaction.
readonly	boolean	false	Keeps focus while preventing mutation.
required	boolean	false	Applies native and accessible required state.
invalid	boolean	false	Exposes invalid visual and ARIA state.
pending	boolean	false	Exposes aria-busy during validation.
touched	boolean	false	Forms/Field state contract.
dirty	boolean	false	Forms/Field state contract.
fluid	boolean	false	Fills the available inline width.
unstyled	boolean	false	Removes all NeuralNg visual classes.
inputId	string	''	Native input id; generated when omitted.
name	string	''	Native form submission name.
inputValue	string	'on'	Native checked submission value.
ariaLabel	string	''	Accessible name when no visible label exists.
checkboxClass	string	''	Additive class on the label root.
inputClass	string	''	Additive class on the native input.
labelClass	string	''	Additive class on projected label text.
classes	NeuralCheckboxClasses \| NeuralTriStateCheckboxClasses	{}	Typed additive classes for structure and value states.

Tri-state inputs

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

Models

checkedModelSignal<boolean> · false

Binary value; generates checkedChange.

valueModelSignal<boolean | null> · false

Tri-state value; generates valueChange.

Events

checkedChangeboolean

Generated by the binary checked model for two-way binding.

valueChangeboolean | null

Generated by the tri-state value model for two-way binding.

stateChangeNeuralCheckboxChange

Binary user action with current and previous values.

stateChangeNeuralTriStateCheckboxChange

Tri-state user action with current and previous values.

touchvoid

Native input lost focus.

Methods

focus(options?: FocusOptions) => void

Focuses the native input.

reset() => void

Resets binary or tri-state value to false.

Typed class slots

Binary slots

rootinputcontrolcheckedControllabel

Tri-state slots

rootinputcontrolcheckedControllabelmixedControl

Public types

NeuralCheckboxChange

{ checked, previousChecked, nativeEvent }

NeuralTriStateCheckboxValue

boolean | null

NeuralTriStateCheckboxChange

{ value, previousValue, nativeEvent }

NeuralCheckboxClasses

{ root?, input?, control?, checkedControl?, label? }

NeuralTriStateCheckboxClasses

NeuralCheckboxClasses & { mixedControl? }

DESIGN TOKENS

Checkbox tokens

Neutral is the reference layer; Glass, Mist and Futuristic override the same component contract.

Layout and typography

--neural-checkbox-gap

Spacing between component items.

--neural-checkbox-width

Component inline size.

--neural-checkbox-size

Component width and height.

--neural-checkbox-control-offset

Control positional offset.

--neural-checkbox-radius

Component corner radius.

--neural-checkbox-font-family

Component font family.

--neural-checkbox-font-size

Component font size.

--neural-checkbox-line-height

Component line height.

Color and state

--neural-checkbox-background

Component background surface.

--neural-checkbox-background-hover

Hovered component background surface.

--neural-checkbox-background-checked

Checked component background surface.

--neural-checkbox-border

Component border shorthand.

--neural-checkbox-border-color-hover

Hovered component border color.

--neural-checkbox-border-color-focus

Focused component border color.

--neural-checkbox-border-color-checked

Checked component border color.

--neural-checkbox-border-color-invalid

Invalid component border color.

--neural-checkbox-mark-color

Mark foreground color.

--neural-checkbox-label-color

Label foreground color.

--neural-checkbox-shadow

Component box shadow.

--neural-checkbox-shadow-focus

Focused component box shadow.

--neural-checkbox-focus-ring

Component keyboard focus ring.

--neural-checkbox-focus-ring-offset

Component focus ring offset.

--neural-checkbox-disabled-opacity

Disabled opacity.

Motion

--neural-checkbox-transition

Component CSS transition.

--neural-checkbox-mark-transition

Mark CSS transition.

Reduced-motion preferences collapse transitions automatically.

Primary

Surface