Primitives

Checkbox

A checkbox supporting the three states checked, unchecked and indeterminate.

forty-cdk/checkbox WAI-ARIA APG

Tick it with the pointer or Space and watch data-state move between checked and unchecked. The box is a <button>, so its whole appearance is your CSS.

Source

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { ForCheckbox } from 'forty-cdk/checkbox';

@Component({
  selector: 'app-checkbox-default-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [ForCheckbox],
  template: `
    <button forCheckbox class="cb-row" [(checked)]="checked">
      <span class="cb">
        <span class="cb-check" aria-hidden="true"></span>
      </span>
      I agree to the terms
    </button>
  `,
  styles: `
    :host {
      display: contents;
    }

    .cb-row {
      display: inline-flex;
      align-items: center;
      gap: 0.6rem;
      padding: 0;
      border: 0;
      background: transparent;
      font: inherit;
      color: var(--ex-text, #17191c);
      cursor: pointer;
    }

    .cb {
      flex: none;
      width: 22px;
      height: 22px;
      display: grid;
      place-items: center;
      border: 2px solid var(--ex-border-strong, #d0c9bc);
      border-radius: 6px;
      background: var(--ex-surface, #ffffff);
      transition:
        background 0.15s ease,
        border-color 0.15s ease;
    }

    .cb-row[data-state='checked'] .cb {
      background: var(--ex-accent, #0e7c6b);
      border-color: var(--ex-accent, #0e7c6b);
    }

    .cb-check {
      display: none;
      width: 6px;
      height: 12px;
      border: solid var(--ex-accent-contrast, #ffffff);
      border-width: 0 2.5px 2.5px 0;
      transform: rotate(45deg) translate(-1px, -1px);
    }

    .cb-row[data-state='checked'] .cb-check {
      display: block;
    }

    @media (prefers-reduced-motion: reduce) {
      .cb {
        transition: none;
      }
    }
  `,
})
export class CheckboxDefaultExample {
  protected readonly checked = signal(false);
}

Headless and styleless. Implements FormCheckboxControl from @angular/forms/signals for [formField] auto-wiring.

When to choose

Checkbox: deferred selection (user is choosing options for a form to apply later). Supports the tri-state mixed value, useful for "select all" parents.
Switch: immediate setting (flipping it changes the world right now). Always binary.

Use the one that matches your semantics. ForCheckbox and ForSwitch are intentionally separate even though they share most of their state surface.

Anatomy

<label>
  <button forCheckbox [(checked)]="agreed">
    <span forCheckboxIndicator></span>
  </button>
  I agree to the terms
</label>

Examples

Tri-state ("select all")

A parent checkbox reflects indeterminate when only some children are selected. Activating it selects or clears them all at once, matching native inputs.

Source

import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
import { ForCheckbox } from 'forty-cdk/checkbox';

interface Topping {
  readonly id: number;
  readonly label: string;
  selected: boolean;
}

@Component({
  selector: 'app-checkbox-select-all-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [ForCheckbox],
  template: `
    <fieldset class="group">
      <button
        forCheckbox
        class="cb-row"
        [checked]="allChecked()"
        [indeterminate]="someChecked()"
        (click)="toggleAll()"
      >
        <span class="cb">
          <span class="cb-check" aria-hidden="true"></span>
          <span class="cb-dash" aria-hidden="true"></span>
        </span>
        Select all toppings
      </button>

      <div class="children">
        @for (topping of toppings(); track topping.id) {
          <button forCheckbox class="cb-row" [(checked)]="topping.selected">
            <span class="cb">
              <span class="cb-check" aria-hidden="true"></span>
            </span>
            {{ topping.label }}
          </button>
        }
      </div>
    </fieldset>
  `,
  styles: `
    :host {
      display: contents;
    }

    .group {
      display: flex;
      flex-direction: column;
      gap: 0.75rem;
      margin: 0;
      padding: 0;
      border: 0;
    }

    .children {
      display: flex;
      flex-direction: column;
      gap: 0.6rem;
      padding-inline-start: 1.75rem;
    }

    .cb-row {
      display: inline-flex;
      align-items: center;
      align-self: flex-start;
      gap: 0.6rem;
      padding: 0;
      border: 0;
      background: transparent;
      font: inherit;
      color: var(--ex-text, #17191c);
      cursor: pointer;
    }

    .cb {
      flex: none;
      width: 22px;
      height: 22px;
      display: grid;
      place-items: center;
      border: 2px solid var(--ex-border-strong, #d0c9bc);
      border-radius: 6px;
      background: var(--ex-surface, #ffffff);
      transition:
        background 0.15s ease,
        border-color 0.15s ease;
    }

    .cb-row[data-state='checked'] .cb,
    .cb-row[data-state='indeterminate'] .cb {
      background: var(--ex-accent, #0e7c6b);
      border-color: var(--ex-accent, #0e7c6b);
    }

    .cb-check,
    .cb-dash {
      display: none;
    }

    .cb-check {
      width: 6px;
      height: 12px;
      border: solid var(--ex-accent-contrast, #ffffff);
      border-width: 0 2.5px 2.5px 0;
      transform: rotate(45deg) translate(-1px, -1px);
    }

    .cb-row[data-state='checked'] .cb-check {
      display: block;
    }

    .cb-dash {
      width: 12px;
      height: 2px;
      border-radius: 1px;
      background: var(--ex-accent-contrast, #ffffff);
    }

    .cb-row[data-state='indeterminate'] .cb-dash {
      display: block;
    }

    @media (prefers-reduced-motion: reduce) {
      .cb {
        transition: none;
      }
    }
  `,
})
export class CheckboxSelectAllExample {
  protected readonly toppings = signal<Topping[]>([
    { id: 1, label: 'Mozzarella', selected: true },
    { id: 2, label: 'Mushrooms', selected: false },
    { id: 3, label: 'Pepperoni', selected: false },
  ]);

  protected readonly allChecked = computed(() => this.toppings().every((t) => t.selected));
  protected readonly someChecked = computed(() => {
    const some = this.toppings().some((t) => t.selected);
    return some && !this.allChecked();
  });

  protected toggleAll(): void {
    const next = !this.allChecked();
    this.toppings.update((list) => list.map((t) => ({ ...t, selected: next })));
  }
}

States

One class and one directive, three states. disabled and readonly both keep the box focusable and announced (per APG) while click and Space are a no-op; they reflect data-disabled and data-readonly, which is all the example's stylesheet keys on.

Source

Default

Disabled

Read-only

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { ForCheckbox } from 'forty-cdk/checkbox';

@Component({
  selector: 'app-checkbox-states-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [ForCheckbox],
  template: `
    <div class="states">
      <div class="state">
        <span class="state-label">Default</span>
        <button forCheckbox class="cb-row" [(checked)]="checked">
          <span class="cb">
            <span class="cb-check" aria-hidden="true"></span>
          </span>
          I agree to the terms
        </button>
      </div>

      <div class="state">
        <span class="state-label">Disabled</span>
        <button forCheckbox class="cb-row" [(checked)]="checked" disabled>
          <span class="cb">
            <span class="cb-check" aria-hidden="true"></span>
          </span>
          I agree to the terms
        </button>
      </div>

      <div class="state">
        <span class="state-label">Read-only</span>
        <button forCheckbox class="cb-row" [(checked)]="checked" readonly>
          <span class="cb">
            <span class="cb-check" aria-hidden="true"></span>
          </span>
          I agree to the terms
        </button>
      </div>
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    .states {
      display: flex;
      flex-direction: column;
      gap: 1.2rem;
    }

    .state {
      display: flex;
      flex-direction: column;
      gap: 0.5rem;
    }

    .state-label {
      font-size: 0.72rem;
      font-weight: 700;
      letter-spacing: 0.06em;
      text-transform: uppercase;
      color: var(--ex-muted, #585d66);
    }

    .cb-row {
      display: inline-flex;
      align-items: center;
      gap: 0.6rem;
      padding: 0;
      border: 0;
      background: transparent;
      font: inherit;
      color: var(--ex-text, #17191c);
      cursor: pointer;
    }

    .cb-row[data-disabled] {
      opacity: 0.5;
      cursor: not-allowed;
    }

    .cb-row[data-readonly] {
      cursor: default;
    }

    .cb {
      flex: none;
      width: 22px;
      height: 22px;
      display: grid;
      place-items: center;
      border: 2px solid var(--ex-border-strong, #d0c9bc);
      border-radius: 6px;
      background: var(--ex-surface, #ffffff);
      transition:
        background 0.15s ease,
        border-color 0.15s ease;
    }

    .cb-row[data-state='checked'] .cb {
      background: var(--ex-accent, #0e7c6b);
      border-color: var(--ex-accent, #0e7c6b);
    }

    .cb-row[data-readonly] .cb {
      border-style: dashed;
    }

    .cb-check {
      display: none;
      width: 6px;
      height: 12px;
      border: solid var(--ex-accent-contrast, #ffffff);
      border-width: 0 2.5px 2.5px 0;
      transform: rotate(45deg) translate(-1px, -1px);
    }

    .cb-row[data-state='checked'] .cb-check {
      display: block;
    }

    @media (prefers-reduced-motion: reduce) {
      .cb {
        transition: none;
      }
    }
  `,
})
export class CheckboxStatesExample {
  protected readonly checked = signal(true);
}

Signal Forms

forCheckbox implements FormCheckboxControl, so a single [formField] binding wires the binary checked value into the form and pulls validity back out. The box is required: blur it unchecked and it reflects data-invalid / data-touched.

Source

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { form, FormField, requiredError, validate } from '@angular/forms/signals';
import { ForCheckbox } from 'forty-cdk/checkbox';

interface Signup {
  readonly terms: boolean;
}

@Component({
  selector: 'app-checkbox-form-field-example',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [FormField, ForCheckbox],
  template: `
    <div class="cb-form">
      <button
        forCheckbox
        class="cb-row"
        [formField]="signupForm.terms"
        aria-label="Accept the terms of service"
      >
        <span class="cb">
          <span class="cb-check" aria-hidden="true"></span>
        </span>
        I accept the terms of service
      </button>
      @if (signupForm.terms().touched() && !signupForm.terms().valid()) {
        <p class="cb-error">You must accept the terms to create an account.</p>
      }
    </div>
  `,
  styles: `
    :host {
      display: contents;
    }

    .cb-form {
      display: flex;
      flex-direction: column;
      gap: 0.75rem;
    }

    .cb-row {
      display: inline-flex;
      align-items: center;
      align-self: flex-start;
      gap: 0.6rem;
      padding: 0;
      border: 0;
      background: transparent;
      font: inherit;
      color: var(--ex-text, #17191c);
      cursor: pointer;
    }

    .cb {
      flex: none;
      width: 22px;
      height: 22px;
      display: grid;
      place-items: center;
      border: 2px solid var(--ex-border-strong, #d0c9bc);
      border-radius: 6px;
      background: var(--ex-surface, #ffffff);
      transition:
        background 0.15s ease,
        border-color 0.15s ease;
    }

    .cb-row[data-state='checked'] .cb {
      background: var(--ex-accent, #0e7c6b);
      border-color: var(--ex-accent, #0e7c6b);
    }

    .cb-row[data-touched][data-invalid] .cb {
      border-color: #ef4444;
    }

    .cb-check {
      display: none;
      width: 6px;
      height: 12px;
      border: solid var(--ex-accent-contrast, #ffffff);
      border-width: 0 2.5px 2.5px 0;
      transform: rotate(45deg) translate(-1px, -1px);
    }

    .cb-row[data-state='checked'] .cb-check {
      display: block;
    }

    .cb-error {
      margin: 0;
      font-size: 0.85rem;
      color: #ef4444;
    }

    @media (prefers-reduced-motion: reduce) {
      .cb {
        transition: none;
      }
    }
  `,
})
export class CheckboxFormFieldExample {
  protected readonly model = signal<Signup>({ terms: false });
  protected readonly signupForm = form(this.model, (path) => {
    validate(path.terms, (ctx) =>
      ctx.value() ? undefined : requiredError({ message: 'Accept the terms' }),
    );
  });
}

API

`ForCheckbox`

Property	Type	Description
`checked`	`model`	Two-way bindable on/off. Required by `FormCheckboxControl`. Default: —
`indeterminate`	`model`	Two-way bindable. When true, `aria-checked="mixed"` regardless of `checked`. Click clears it. UI-only and not part of the form value. Default: —
`disabled` / `readonly` / `required` / `invalid` / `pending`	`input`	Reflected as the matching `aria-` / `data-` attributes. A disabled checkbox stays focusable (per APG), with `aria-disabled="true"` + `data-disabled` and no native `disabled`; click is a no-op. Default: —
`name`	`input`	Reflected on `name` (empty string omits the attribute). Default: `''`
`errors`	`input`	Validation errors fed by `[formField]`. Default: —
`touched`	`model`	Set to `true` on blur. Default: —

Data attribute	Values
`data-state`	`checked` \| `unchecked` \| `indeterminate`
`data-disabled`	present \| absent
`data-readonly`	present \| absent

`ForCheckboxIndicator`

Optional styling slot inside a [forCheckbox]. Mirrors the parent's data-state so you can show or hide a check / dash without per-state bindings.

Data attribute	Values
`data-state`	`checked` \| `unchecked` \| `indeterminate`

Keyboard

Key	Action
`Space`	Toggle the checkbox. The only key APG mandates.
`Enter`	Also toggles. A documented superset, not an APG violation.

Activating an indeterminate checkbox clears indeterminate and toggles checked (matches native <input type="checkbox">).

Both keys work on any host element. On a <button> they come from native button behavior; on any other host (<div>, <span>, or a hostDirectives wrapper's own host) the directive adds tabindex="0" and synthesizes the same activation, so a styled-from-scratch checkbox is never announced as a checkbox it is impossible to operate. Space keydown always blocks page scrolling; the toggle fires on its keyup.

Accessibility

Implements the WAI-ARIA Checkbox pattern.

Provide an accessible name. Wrap the button in a <label>, or set aria-labelledby / aria-label. Without one, the control is announced as just "checkbox" with no purpose.
Any host element works. A <button> is the recommended host (the directive forces type="button" through a host binding, so it never submits a surrounding form even if you write type="submit" yourself), but a non-button host gets tabindex="0" and synthesized Space / Enter activation, so it is keyboard-operable too. A non-button host gets no type attribute at all, because type is not valid on a <div> / <span> and there is no form submission to protect against.
role="checkbox" with aria-checked="mixed" is the canonical tri-state contract. Some legacy screen readers handle "mixed" differently, so test with your target SRs.

Styling

forty-cdk ships no styles: put your own class on each piece and key your CSS off the data-* attributes listed under API, not off the for* selectors (Styling forty-cdk explains why).

.cb-check {
  display: inline-block;
  width: 6px;
  height: 12px;
  border: solid currentColor;
  border-width: 0 2px 2px 0;
  transform: rotate(45deg);
}

.cb-row[data-state='unchecked'] .cb-check {
  display: none;
}

.cb-row[data-state='indeterminate'] .cb-check {
  width: 12px;
  height: 0;
  transform: none;
}

Wrapping in a design system

Wrapping form primitives documents both supported wrapper patterns: hostDirectives with the exported FOR_CHECKBOX_HOST_DIRECTIVE_INPUTS / FOR_CHECKBOX_HOST_DIRECTIVE_OUTPUTS name tuples, and subclassing.