CngxCheckbox
cngx-checkbox
projects/common/interactive/checkbox/checkbox.component.ts
Import#
import { CngxCheckbox } from '@cngx/common/interactive'
Description#
Single-value boolean checkbox with indeterminate support and W3C
role="checkbox" semantics. Click, Space, and Enter all advance
value; an indeterminate checkbox advances to value=true,
indeterminate=false in a single step (per WAI-ARIA tristate
semantics - there is no path that lands the checkbox back in
'mixed' from a user click).
value and indeterminate are both ModelSignal<boolean> so
consumers can two-way-bind both: [(value)] for the canonical
checked/unchecked state, [(indeterminate)] for the tri-state
marker most often driven by a parent group's "some-but-not-all"
computation. disabled is also a ModelSignal<boolean> to keep
the CngxFormBridge's setDisabledState write path consistent
across the family.
Visual indicator state is delegated to <cngx-checkbox-indicator>
from @cngx/common/display; this interactive molecule owns role,
keyboard, and ARIA wiring and composes the display atom. Per
Pillar 3, the visual atom is
reused - never re-drawn here.
aria-checked is a reactive computed: indeterminate() ? 'mixed' : value() ? 'true' : 'false'. The description span for
disabledReason follows the same always-in-DOM rule as
CngxToggle.
<cngx-checkbox [(value)]="acceptTerms">I accept the terms</cngx-checkbox>
<cngx-checkbox
[(value)]="allSelected()"
[(indeterminate)]="someSelected() && !allSelected()"
(valueChange)="toggleAll($event)"
>Select all</cngx-checkbox>Metadata#
Host#
Providers#
CNGX_CONTROL_VALUE- useExisting
CngxCheckbox CNGX_FORM_FIELD_CONTROL- useExisting
CngxCheckbox
Relationships
Index#
Properties
Derived State
HostBindings
HostListeners
Inputs#
TemplateRef | null nullTemplateRef | null nullstring | nullOptional id of an external error message element (e.g. a sibling
rendered by <cngx-form-field> or a consumer-owned <span>).
The host emits aria-errormessage="<id>" only when
aria-invalid="true" — symmetric with the sibling aria-invalid
host binding (both gate on invalid() || errorState()). Consumers
MUST render an element with the supplied id; passing an id without
a matching element produces a dangling AT reference. Default
null skips the attribute entirely.
nullBridge-writable invalid state. model<boolean> mirrors disabled
so external integrations (RF/Signal-Forms bridges, custom validity
adapters) can drive it without a parallel API path - consumers
typically read only.
falseOutputs#
Bridge-writable invalid state. model<boolean> mirrors disabled
so external integrations (RF/Signal-Forms bridges, custom validity
adapters) can drive it without a parallel API path - consumers
typically read only.
Instance Properties#
Methods#
HostBindings#
| Binding | Expression |
|---|---|
[attr.id] | id() |
[attr.aria-checked] | ariaChecked() |
[attr.aria-disabled] | disabled() ? "true" : null |
[attr.aria-invalid] | ariaInvalid() ? "true" : null |
[attr.aria-errormessage] | ariaInvalid() ? errorMessageId() : null |
[attr.aria-describedby] | describedId |
[attr.tabindex] | hostTabindex() |
[class.cngx-checkbox--checked] | value() |
[class.cngx-checkbox--indeterminate] | indeterminate() |
[class.cngx-checkbox--disabled] | disabled() |
HostListeners#
| Event | Handler |
|---|---|
(click) | click() |
(keydown.space) | keydown.space() |
(keydown.enter) | keydown.enter() |
(focusin) | focusin() |
(focusout) | focusout() |
Default visuals for the interactive shell around
<cngx-checkbox-indicator>. The host carries .cngx-checkbox and
renders the indicator plus a .cngx-checkbox__label slot for the
projected label text and a .cngx-checkbox__sr-only slot for
assistive-only copy. The --cngx-checkbox-color and
--cngx-checkbox-disabled-opacity tokens are owned by
CngxCheckboxIndicator and read here without re-registration so
the vocabulary stays unified.
State modifiers
--disabled-cursor: not-allowed+ opacity dim via--cngx-checkbox-disabled-opacity
Slots
.cngx-checkbox__label- projected label content.cngx-checkbox__sr-only- visually-hidden copy for AT
Inheritance
Layout and focus tokens cascade through the foundation:
--cngx-checkbox-gap->--cngx-space-sm--cngx-checkbox-focus-radius->--cngx-radius-sm--cngx-checkbox-sibling-gap- direct (defaults to1rem)
Adjacent-sibling spacing (.cngx-checkbox + .cngx-checkbox) sits
OUTSIDE the @scope block because @scope's subtree semantics
block the + combinator from reaching a sibling scope-root.
Override the sibling-gap token with 0 when the consumer wraps
siblings in their own flex/grid container.
Index#
Layout
*0.5remGap between the indicator and the label slot. Falls back to
--cngx-space-sm.
*1remHorizontal spacing between adjacent inline <cngx-checkbox>
siblings. Override with 0 if the consumer wraps siblings in
its own flex/grid container.
State / Focus
*2px solid currentColorFocus-ring outline shorthand applied via outline on the host.
*0.25remCorner radius applied while focused - keeps the ring rounded around the inline shell.