On this page

Choices

Switch released

A setting that takes effect the moment it is flipped, with no Save button beside it.

Import@pacit/components/switch
Selectorpct-switch

Implements the W3C ARIA APG Switch pattern ↗

Wi-Fi

Turns off when you leave the house

import { Component, signal } from '@angular/core';
import { PctSwitch } from '@pacit/components/switch';

/** On or off, effective immediately — that immediacy is what separates it from a checkbox. */
@Component({
  selector: 'demo-switch',
  imports: [PctSwitch],
  template: `
    <pct-switch
      label="Wi-Fi"
      hint="Turns off when you leave the house"
      [(checked)]="wifi"
    />
  `,
})
export class SwitchDemo {
  readonly wifi = signal(true);
}

switch.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 { PctSwitch } from '@pacit/components/switch';

Exported	What it is
`PctSwitch`component`pct-switch`	Switch. A setting that takes effect the moment it is moved, drawn as a track the thumb travels along — the ARIA APG's Switch pattern, built on the same native `<input type="checkbox">` as `PctCheckbox` and carrying `role="switch"` over it.

<pct-switch label="Wi-Fi" [(checked)]="wifi" />

Examples

Every state, running

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

On, off, and out of reach

A switch takes effect at once — there is no Save behind it — so a disabled one says "this setting is not yours here" rather than "fill this in later".

Notifications

A sound and a badge

Two-factor sign-in

Managed by your organisation

Location

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.

Switch. A setting that takes effect the moment it is moved, drawn as a track the thumb travels along — the ARIA APG's Switch pattern, built on the same native <input type="checkbox"> as PctCheckbox and carrying role="switch" over it.

Inputs

Name	Type	What it does
`checked`two-waydefault `false`	`boolean`	On/off — 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`	The switch is a native checkbox, which 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 switch with no visible `label` — an INPUT rather than an `aria-label` written on the tag, for the same reason as on the checkbox: the role sits on the `<input>` inside, the host has no role at all, and an ARIA name on a roleless element is ignored (`req-a11y-built-in`).
`ariaLabelledby`default `''`	`string`	As `ariaLabel`, for a name that already stands somewhere on the page.

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-switch`
`data-pct-checked`	`checked() ? "" : 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, PctSwitchHarness 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
`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 switch
`thumb`	`[data-pct-part="thumb"]`	the knob — painted over the control, and it lets the pointer through to it
`track`	`[data-pct-part="track"]`	the pill the thumb travels
`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-switch-fg-disabled{pct.text-disabled}`#64748b	Text colour of the switch while disabled.
`--pct-switch-fg-invalid{pct.danger}`#b91c1c · #f87171	Text colour of the switch when invalid.
`--pct-switch-fg-warning{pct.warning}`#b45309 · #fbbf24	Text colour of the warning line (0087); the track keeps its colour, a warning being no fault of the control.
`--pct-switch-gap{pct.space.3}`8px	Gap between the switch and its label.
`--pct-switch-height`24px	Height of the switch.
`--pct-switch-hint-fg{pct.text-muted}`#334155 · #e2e8f0	Text colour of the hint.
`--pct-switch-label-fg{pct.text}`#0f172a · #ffffff	Text colour of the label.
`--pct-switch-padding-x`3px	Horizontal padding of the switch.
`--pct-switch-radius`999px	Corner radius of the switch.
`--pct-switch-target-min{pct.target.min}`24px	Touch-target floor of the switch.
`--pct-switch-thumb-bg{pct.border-strong}`#64748b	Background of the thumb.
`--pct-switch-thumb-bg-checked{pct.on-primary}`#ffffff · #0f172a	Background of the thumb when checked.
`--pct-switch-thumb-bg-disabled{pct.text-disabled}`#64748b	Background of the thumb while disabled.
`--pct-switch-thumb-size`16px	Size of the thumb.
`--pct-switch-track-bg{pct.surface}`#ffffff · #0f172a	Background of the track.
`--pct-switch-track-bg-checked{pct.primary}`#2563eb · #60a5fa	Background of the track when checked.
`--pct-switch-track-bg-disabled{pct.surface-disabled}`#f1f5f9 · #1e293b	Background of the track while disabled.
`--pct-switch-track-border{pct.border-strong}`#64748b	Edge colour of the track.
`--pct-switch-track-border-checked{pct.primary}`#2563eb · #60a5fa	Edge colour of the track when checked.
`--pct-switch-track-border-disabled{pct.border}`#e2e8f0 · #334155	Edge colour of the track while disabled.
`--pct-switch-track-border-hover{pct.text-muted}`#334155 · #e2e8f0	Edge colour of the track on hover.
`--pct-switch-track-border-invalid{pct.danger}`#b91c1c · #f87171	Edge colour of the track when invalid.
`--pct-switch-width`40px	Width of the switch.

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-switch-track-bg-checked: #0f766e;
  --pct-switch-thumb-bg: #ffffff;
}

Wi-Fi

Turns off when you leave the house

Accessibility

Measured, not assumed

Pattern: Switch — the role="switch" variant built on a native checkbox, which the APG's own HTML example is

Keyboard

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

No handling of its own (req-api-platform) — and that is the point of the native road: the APG lists Space for the pattern and the platform already implements it. readonly blocks the change without losing focusability.

Evidence

What the repository holds for this component

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

96.77%mutation score60 of 62 mutants killed

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

14colour pairs measuredlight and dark, at every token build

2visual baselinesChromium, the sandbox's own pictures

7elements in the preview4 listeners · 1 render to settle · 3210 µs in jsdom, held exactly but for the clock

Decisions behind it

0039A state the platform publishes is not ours to write
0005Signal forms without ControlValueAccessor
0003Wrapper and control
lesson-12FormCheckboxControl requires checked, not value
lesson-112An ARIA attribute over a native state is written by us and read by nobody
lesson-14Formal conformance does not mean good quality
lesson-158A box painted over a transparent control is the box the pointer lands on

Known limitations

No third state. ARIA gives switch true and false and nothing else, so there is no indeterminate here — and no audit would have said so, which is why the absence of the input is the gate rather than a rule somebody has to remember.
No on/off text inside the track. A word drawn there would have to be aria-hidden (the role already says the state) and would need a string per language for something the position already tells the eye. It is a limitation rather than a decision: a consumer who wants it today has to draw it themselves.

pacit