On this page

Choices

Checkbox released

A box the reader ticks, with the third state a parent of many options needs.

Source

Import@pacit/components/checkbox
Selectorpct-checkbox

Implements the W3C ARIA APG Checkbox (tri-state) pattern ↗

Send me release notes

Signed the agreement

Release notes: yes

import { Component, signal } from '@angular/core';
import { PctCheckbox } from '@pacit/components/checkbox';

/** A native input under the paint — the checkmark is drawn, the semantics are not. */
@Component({
  selector: 'demo-checkbox',
  imports: [PctCheckbox],
  styles: ':host { display: grid; gap: 8px; }',
  template: `
    <pct-checkbox label="Send me release notes" [(checked)]="notes" />
    <pct-checkbox label="Signed the agreement" [checked]="true" disabled />
    <p>Release notes: {{ notes() ? 'yes' : 'no' }}</p>
  `,
})
export class CheckboxDemo {
  readonly notes = signal(true);
}

checkbox.demo.ts — the same file runs here and is highlighted under Code

Start here

Usage

One import per component, and the shortest possible use — the package itself is installed once, on the start page.

Import this component

import { PctCheckbox } from '@pacit/components/checkbox';

Exported	What it is
`PctCheckbox`component`pct-checkbox`	Checkbox. A native signal-forms control — it implements `FormCheckboxControl` (req-api-signal-forms). That contract requires `checked`, and the component may not define a `value` property (reserved for `FormValueControl`).

<pct-checkbox label="Send me release notes" [(checked)]="notes" />

Examples

Every state, running

Each example is the component itself, not a screenshot. Open the code under any of them.

The states a form drives

required, invalid and touched are the form's to set — the FormField directive keeps them in sync — and here they are set by hand to show each face: the error appears once the box is both invalid and touched, never before.

I accept the terms

Required to continue

Remember this device

Beta features

Not on this plan

API

What it reads, and what it writes back

Read from the source at build time — the types, the defaults and the lines of documentation are the library's own.

unreleased marks 1 of them: on main, and not in @pacit/components@0.2.0 — the next release names the version.

Checkbox. A native signal-forms control — it implements FormCheckboxControl (req-api-signal-forms). That contract requires checked, and the component may not define a value property (reserved for FormValueControl).

Inputs

Name	Type	What it does
`checked`two-waydefault `false`	`boolean`	Checked state — the only required field of the `FormCheckboxControl` contract.
`disabled`default `false`	`boolean`	Blocks the control and greys it — the native `disabled`, so it leaves the tab order as well. With `[formField]` the directive writes it, as it writes every input of the `FormUiControl` contract.
`readonly`default `false`	`boolean`	A native checkbox has no `readonly`, so the click is swallowed here instead; the control stays focusable, unlike under `disabled`, and `aria-readonly` says so.
`invalid`default `false`	`boolean`	The form's verdict; shown only once `touched`, so an empty form does not open red.
`touched`default `false`	`boolean`	Whether the user has left the field once; with `invalid` it gates the error face.
`required`default `false`	`boolean`	Marks the label with the required sign; with `[formField]` it follows the schema's `required()`.
`errors`default `[]`	`readonly ValidationError.WithOptionalFieldTree[]`	The form's validation errors; the first one's `message` takes the hint's place once the field is touched.
`warnings`unreleaseddefault `undefined`	`readonly ValidationError.WithOptionalFieldTree[] \| undefined`	A verdict without a veto (0087): shown after the error and before the hint once the field is touched, in the warning tone, with `aria-invalid` untouched. Left unbound, the control reads what `pctWarn()` wrote for its own `[formField]`; bound — `[]` included — the list given stands.
`name`default `''`	`string`	The native `name` — what a form submission calls the value.
`label`default `''`	`string`	The visible label, rendered by the control itself when it stands outside a `pct-field`; inside one, the field's label is the name.
`hint`default `''`	`string`	A line of help under the control, outside a `pct-field`; the first error message takes its place while the field is invalid and touched.
`ariaLabel`default `''`	`string`	The accessible name of a checkbox with no visible `label` — an INPUT rather than an `aria-label` written on the tag, because the tag cannot carry one: the role sits on the `<input>` inside, the host has no role at all, and an ARIA name on a roleless element is ignored (`aria-label` is prohibited for the `generic` role) (`req-a11y-built-in`).
`ariaLabelledby`default `''`	`string`	As `ariaLabel`, for a name that already stands somewhere on the page — the header of the column a checkbox in a row belongs to. It wins over `ariaLabel` and over `label`.
`indeterminate`default `false`	`boolean`	Indeterminate state (a partial choice in a group, say). It is the native `indeterminate` PROPERTY and nothing else: the accessible tree reports it as `mixed` from the property alone, and an `aria-checked` written beside it would be ignored in both directions — measured in three engines and in Chromium's own tree, so none is written (0039, `lesson-112`).

Outputs

Name	Payload	When it fires
`touch`	`void`	Emitted on blur — lets the form mark the field as touched.

What it writes on the element

The hooks a stylesheet or a test can hold. Stable by contract — the parts inventory gate fails the build when one disappears.

Attribute	Bound to	Note
`class`	`pct-checkbox`
`data-pct-checked`	`checked() ? "" : null`
`data-pct-indeterminate`	`indeterminate() ? "" : null`
`data-pct-invalid`	`showInvalid() ? "" : null`
`data-pct-warning`	`warningLit() ? "" : null`
`data-pct-disabled`	`disabled() ? "" : null`
`data-pct-in-field`	`inField ? "" : null`

Styling

Parts to select, tokens to override

Two ways in, both stable. No class names to depend on.

Parts

In a test, PctCheckboxHarness from @pacit/components/testing reads a part by the name below and a state by its attribute — the harness gate holds the names to the package.

Part	Selector	What it is
`box`	`[data-pct-part="box"]`	the square drawn over it
`control`	`[data-pct-part="control"]`	the native input
`error`	`[data-pct-part="error"]`	the message when invalid
`hint`	`[data-pct-part="hint"]`	the hint under the label
`label`	`[data-pct-part="label"]`	the label beside the box
`mark`	`[data-pct-part="mark"]`	the check inside the box
`warning`	`[data-pct-part="warning"]`	the message when the value is allowed and suspect — after the error, before the hint (0087)

Tokens

Every value the component reads, with the light and the dark default. Override a token at any scope and it cascades like any custom property.

Token	Styles
`--pct-checkbox-bg{pct.surface}`#ffffff · #0f172a	Background of the box.
`--pct-checkbox-bg-checked{pct.primary}`#2563eb · #60a5fa	Background of the box when checked.
`--pct-checkbox-bg-disabled{pct.surface-disabled}`#f1f5f9 · #1e293b	Background of the box while disabled.
`--pct-checkbox-border{pct.border-strong}`#64748b	Edge colour of the box.
`--pct-checkbox-border-checked{pct.primary}`#2563eb · #60a5fa	Edge colour of the box when checked.
`--pct-checkbox-border-disabled{pct.border}`#e2e8f0 · #334155	Edge colour of the box while disabled.
`--pct-checkbox-border-hover{pct.text-muted}`#334155 · #e2e8f0	Edge colour of the box on hover.
`--pct-checkbox-border-invalid{pct.danger}`#b91c1c · #f87171	Edge colour of the box when invalid.
`--pct-checkbox-fg-checked{pct.on-primary}`#ffffff · #0f172a	Colour of the check mark.
`--pct-checkbox-fg-disabled{pct.text-disabled}`#64748b	Colour of the check mark while disabled.
`--pct-checkbox-fg-invalid{pct.danger}`#b91c1c · #f87171	Colour of the check mark when invalid.
`--pct-checkbox-fg-warning{pct.warning}`#b45309 · #fbbf24	Text colour of the warning line (0087); the mark keeps its colour, a warning being no fault of the control.
`--pct-checkbox-gap{pct.space.3}`8px	Gap between the box and its label.
`--pct-checkbox-hint-fg{pct.text-muted}`#334155 · #e2e8f0	Text colour of the hint.
`--pct-checkbox-label-fg{pct.text}`#0f172a · #ffffff	Text colour of the label.
`--pct-checkbox-radius`4px	Corner radius of the box.
`--pct-checkbox-size`18px	Size of the box.
`--pct-checkbox-target-min{pct.target.min}`24px	Touch-target floor of the box.

Theming

A brand override in a few declarations. Scope it to a theme attribute, a page or one container — the component never notices.

[data-theme='brand'] {
  --pct-checkbox-bg-checked: #0f766e;
  --pct-checkbox-border-checked: #0f766e;
  --pct-checkbox-fg-checked: #ffffff;
}

Send me release notes

Signed the agreement

Release notes: yes

Accessibility

Measured, not assumed

Pattern: Checkbox (tri-state) — the third state is the native indeterminate property, which the accessible tree reports as mixed; no aria-checked is written (0039)

key	effect	test
`Space`	toggle	native `<input type="checkbox">`

Evidence

What the repository holds for this component

Read at build time from the tracked snapshots, not typed here.

96.83%mutation score61 of 63 mutants killed

5 × 3e2e cases × enginesplus the shared audits: axe, forced colors, preferences, size, hydration

13colour pairs measuredlight and dark, at every token build

2visual baselinesChromium, the sandbox's own pictures

17elements in the preview7 listeners · 1 render to settle · 5099 µs in jsdom, held exactly but for the clock

Decisions behind it

0005Signal forms without ControlValueAccessor
0003Wrapper and control
0028An icon set is a component, and an icon's box is the contract
lesson-12FormCheckboxControl requires checked, not value
lesson-112An ARIA attribute over a native state is written by us and read by nobody
lesson-40A state carried by background alone disappears in high contrast
lesson-70A media query adds no specificity, and the browser it is written for hides that
lesson-14Formal conformance does not mean good quality
lesson-24The part-name collision repeated itself with the wrapper

Known limitations

No switch variant — that is a separate component despite the same FormCheckboxControl contract, because the semantics differ ("turn on now" vs "tick to submit").

pacit