Getting StartedInstall and bootstrap headless foundations 4
LayoutHeadless structural primitives for expandable and container patterns 6
OverlayHeadless modal and floating layer behavior 3
FeedbackHeadless notification and status communication patterns 5
FormHeadless input and selection contracts 17
UtilityReusable action, identity, and clipboard behavior 6
NavigationHeadless trails, trees, menus, and command surfaces 7
Overview API Styling Examples

API reference

Headless checkbox is a single directive surface. Attach tngCheckbox to a native <input> element and let the directive normalize checkbox semantics, tri-state ARIA, and styling hooks for you.

tngCheckbox (directive)

Attach to input[tngCheckbox]. The directive itself writes type="checkbox" on the host, so adding type manually is optional.

Directive attachment

html
<input tngCheckbox />
InputTypeDefaultNotes
checkedboolean | '' | stringfalseControls the committed checked state.
indeterminateboolean | '' | stringfalseEnables mixed mode and resolves aria-checked="mixed".
disabledboolean | '' | stringfalseBlocks interaction and reflects the native disabled attribute.
readonlyboolean | '' | stringfalse Keeps the checkbox focusable, but user toggles are reverted after the native change event fires.
requiredboolean | '' | stringfalseReflects the native required attribute and emits data-required.
invalidboolean | null | '' | 'true' | 'false'nullExplicit invalid override for styling and ARIA.
ariaInvalidboolean | null | '' | 'true' | 'false'nullAlternative invalid signal when validation is owned outside the checkbox itself.
ariaDescribedBystring | nullnullConnects helper, description, or error text by id.
name, valuestring | nullnullSupports native form submission with stable attribute reflection.

Output attributes

AttributeWhen setPurpose
typeAlwaysForces the host to be a checkbox input.
aria-checkedAlwaysResolves to true, false, or mixed.
data-stateAlwaysUnified state selector: checked | unchecked | mixed.
data-checked, data-unchecked, data-mixedState specificConvenient hooks for visuals that target exactly one state.
data-focused, data-focus-visibleDuring focus lifecycleLets pointer and keyboard focus styling diverge cleanly.
data-disabled, data-readonly, data-required, data-invalidWhen activeMirrors interaction and validation state on the native input.
aria-describedby, aria-invalid, aria-readonlyWhen configuredReflects assistive state without requiring a wrapper component.
disabled, required, name, valueWhen configuredPreserves native form behavior and submission semantics.

Change handling

The directive does not emit a custom Angular output. Read the next state from the native change event target and persist it in your own signal or store.

If the checkbox is readonly, the native event still fires, but the directive restores the previous checked and mixed values on the same event cycle.

Read native change events

ts
import { Component, signal } from '@angular/core';
import { TngCheckbox } from '@tailng-ui/primitives';

@Component({
  selector: 'app-release-flags',
  imports: [TngCheckbox],
  templateUrl: './release-flags.component.html',
})
export class ReleaseFlagsComponent {
  readonly marketingOptIn = signal(false);

  onMarketingOptInChange(event: Event): void {
    const target = event.target;
    if (!(target instanceof HTMLInputElement)) {
      return;
    }

    this.marketingOptIn.set(target.checked);
  }
}

<label>
  <input tngCheckbox (change)="onMarketingOptInChange($event)" />
  <span>Marketing release email</span>
</label>