Headless checkbox

Headless checkbox keeps the native <input type="checkbox"> element in place and adds a consistent state contract for checked, mixed, readonly, invalid, and keyboard-focus styling.

• Binary and tri-state behavior with checked and indeterminate.
• Readonly support that keeps the control focusable while reverting user toggles.
• Stable data-* hooks for custom visuals without wrapper lock-in.

Installation

Import only the checkbox primitive when your app already owns the surrounding markup.

import { TngCheckbox } from '@tailng-ui/primitives';

Basic usage

The directive can live on a bare input, but in practice you usually wrap it in a <label> so the text stays clickable and supplies the accessible name.

<input tngCheckbox />

<label class="headless-checkbox-row">
  <input tngCheckbox [checked]="true" />
  <span>Email release updates</span>
</label>

<label class="headless-checkbox-row">
  <input
    tngCheckbox
    [indeterminate]="true"
    [ariaDescribedBy]="'selection-help'"
  />
  <span>Deployment checklist (mixed)</span>
</label>
<p id="selection-help">One or more child checks are still pending.</p>

Accessibility baseline

• aria-checked resolves to true, false, or mixed.
• readonly keeps the native checkbox in the tab order.
• data-focus-visible makes keyboard-only focus styling straightforward.