GUILD OF GLEKS UIv21.19.0

gog-checkbox

Checkbox

A form-ready checkbox with five sizes, an indeterminate state, and full ControlValueAccessor support for Angular Forms.

Overview

Import the component and drop it into a template.

typescript
import { CheckboxComponent } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [CheckboxComponent],
})

Basic usage — a labelled checkbox bound with [(checked)]:

checked: false

<gog-checkbox label="I agree" [(checked)]="agreed" />
<p>checked: {{ agreed() }}</p>

Examples

Sizes and states

Off, on, indeterminate, and both disabled, in the five sizes — the box, the tick, the dash and the label scale together. indeterminate and checked are separate inputs and the dash wins while both are set. The lengths come from the shared --gog-control-checkbox-* scale that gog-radio-group reads too, which is why a checkbox and a radio line up on a form.

xsm
sm
md
lg
slg
@for (size of sizes; track size) {
  <div>
    <span>{{ size }}</span>
    <gog-checkbox [size]="size" label="Off" />
    <gog-checkbox [size]="size" label="On" [checked]="true" />
    <!-- indeterminate wins while both are set: the "some of them" state. -->
    <gog-checkbox [size]="size" label="Mixed" indeterminate />
    <gog-checkbox [size]="size" label="Disabled" disabled />
    <gog-checkbox [size]="size" label="Disabled, on" disabled [checked]="true" />
  </div>
}

The label, and none

The control is a <label> around a real <input type="checkbox">, so the text is the accessible name — no for to wire up, pressing the text toggles the box. ariaLabel is for the case with no visible text, which is the only case it applies to. A long label wraps rather than pushing the box out of line.

<gog-checkbox label="Email me about releases" />

<!-- No visible text: ariaLabel names it — a row-selection checkbox in a table. -->
<gog-checkbox ariaLabel="Select this row" />

<!-- A long label wraps in a narrow column rather than pushing the box out of line. -->
<div style="max-width: 16rem">
  <gog-checkbox
    label="A label long enough to wrap in a narrow column, which it does rather than pushing the box out of line"
  />
</div>

Full width

Off by default: a checkbox is as wide as its label, so a row of them reads as a row. fullWidth fills the container — the dashed box here — leaving the rest of the line clickable.

<gog-checkbox label="fullWidth unset" />
<gog-checkbox label="fullWidth" fullWidth />

Custom check icon — gogCheckboxIcon

The slot replaces the glyph inside the box, drawn through gog-icon so it takes the size the scale gives it. The box, its border, its fill and every state stay the component's. It is the checked glyph only: the indeterminate dash is drawn by the stylesheet, and a template does not reach it — the third checkbox shows it.

built-in tick

gogCheckboxIcon

the same slot, indeterminate

<div>
  <p>built-in tick</p>
  <gog-checkbox label="Starred" [checked]="true" />
</div>

<div>
  <p>gogCheckboxIcon</p>
  <gog-checkbox label="Starred" [(checked)]="starred">
    <ng-template gogCheckboxIcon>
      <gog-icon name="star" />
    </ng-template>
  </gog-checkbox>
</div>

<!-- The slot replaces the tick only: the indeterminate dash is the component's own. -->
<div>
  <p>the same slot, indeterminate</p>
  <gog-checkbox label="Starred" indeterminate>
    <ng-template gogCheckboxIcon>
      <gog-icon name="star" />
    </ng-template>
  </gog-checkbox>
</div>

Select all

The classic parent row: checked when every child is, indeterminate when some are, and a press on it sets them all. The state is computed from the children — see the next example for why it has to be.

selected: 1 / 3

<div>
  <!-- The parent is driven from its children: checked when all are, indeterminate when some are. -->
  <gog-checkbox
    label="Subscribe to all"
    [checked]="allSelected()"
    [indeterminate]="someSelected()"
    (checkedChange)="toggleAll($event)"
  />
  <div style="padding-inline-start: 28px">
    @for (topic of topics; track topic.id) {
      <gog-checkbox
        size="sm"
        [label]="topic.name"
        [checked]="selected().includes(topic.id)"
        (checkedChange)="toggle(topic.id, $event)"
      />
    }
  </div>
</div>
<p>selected: {{ selected().length }} / {{ topics.length }}</p>

indeterminate is an input, not a model

A native checkbox resolves indeterminate on the first click; here the dash is drawn from the input, so a press changes checked and leaves indeterminate as it was. Press the checkbox below a few times: checked flips under the dash and nothing visible moves. That is what lets a parent row be driven from its children rather than from its own presses — and it means the state is yours to compute. Since 21.15.0 the element's own indeterminate property is written back after a press, so an input:indeterminate rule or a test reading the element agrees with the screen.

checked: false · 0 checkedChange

<!-- A press changes checked and leaves indeterminate as it was: the dash never moves. -->
<gog-checkbox
  label="indeterminate, never cleared"
  indeterminate
  [(checked)]="checked"
  (checkedChange)="changes.update((n) => n + 1)"
/>
<p>checked: {{ checked() }} · {{ changes() }} checkedChange</p>

Two-way binding

checked is a model: [(checked)], or [checked] with (checkedChange).

checked: false · 0 checkedChange

<gog-checkbox
  label="Email me about releases"
  [(checked)]="subscribed"
  (checkedChange)="changes.update((n) => n + 1)"
/>
<p>checked: {{ subscribed() }} · {{ changes() }} checkedChange</p>

Reactive forms, and the error a checkbox does not draw

A ControlValueAccessor: wire it with [formControl] or formControlName instead of [(checked)], never both. Validators.requiredTrue is how "you must tick this" is written. There is no errorMessage: a checkbox has no error line of its own, so the message belongs to the form around it. Disabling through the form ends up as disabled on the native input.

value: false · valid: false · touched: false · disabled: false

<div>
  <gog-checkbox label="I accept the terms" [formControl]="control" />
</div>

<div>
  <gog-button variant="outline" size="sm" (gogClick)="control.markAsTouched()">
    markAsTouched()
  </gog-button>
  <gog-button variant="outline" size="sm" (gogClick)="toggleDisabled()">
    {{ control.disabled ? 'enable()' : 'disable()' }}
  </gog-button>
</div>

<p>
  value: {{ control.value }} · valid: {{ control.valid }} · touched: {{ control.touched }} ·
  disabled: {{ control.disabled }}
</p>

<!-- A checkbox draws no error line of its own: the form renders this one. -->
@if (control.touched && control.invalid) {
  <p role="alert">You need to accept the terms.</p>
}

App-wide defaults — GOG_CONFIG

control.size sets the default size for every checkbox under the provider; an instance's own input still wins. In an app the provider goes in app.config.ts — see Global Configuration.

<gog-checkbox label="Size from the config (lg)" [checked]="true" />
<gog-checkbox size="sm" label='size="sm" — the instance wins' [checked]="true" />

Accessibility

A native input inside a native label: the role, the state, the keyboard and the name all come from the platform rather than from ARIA. The box you see is a span and is not focusable; the input under it is.

  • Keyboard — Tab reaches it, Space toggles it.
  • State — checked is the input's own property, so no attribute appears for it. indeterminate, which has no native attribute, is announced through aria-checked="mixed" — the one piece of ARIA this component needs.
  • Name — the label, or ariaLabel when there is no visible text.

API Reference

Inputs

NameTypeDefaultDescription
checkedboolean (model)falseTwo-way bindable checked state via [(checked)]. Also the state Angular Forms drives through writeValue/registerOnChange when used with formControlName/[formControl]/ngModel — don't wire both to the same instance.
labelstring''Visible label rendered next to the box. Takes priority over ariaLabel when present.
ariaLabelstring''Accessible name used only when label is empty — falls back onto the native input.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg'GOG_CONFIG.control.size ?? 'md'Box, label and check-icon size, from the --gog-control-checkbox-* scale gog-radio-group shares.
indeterminatebooleanfalseRenders a dash instead of the checkmark and sets aria-checked="mixed", regardless of checked. Purely presentational — does not affect the underlying checked value.
disabledbooleanfalseSets the native disabled attribute and blocks toggling. A FormControl.disable() has the same effect via setDisabledState.
fullWidthbooleanfalseStretches the checkbox row to fill its container.

Outputs

NamePayloadDescription
checkedChangebooleanEmitted when the box is toggled. Comes from the checked model input.

Content slots

DirectiveContextDescription
gogCheckboxIcon—Replaces the checkmark drawn inside the box when checked. The indeterminate dash is not replaced.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.control.size

Styling Tokens

Every CSS custom property the checkbox paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-checkbox-gapGap between box and label.
--gog-checkbox-radiusBox corner radius.
--gog-checkbox-border-width / -style / -colorBox border.
--gog-checkbox-bg / -checked-bg / -checked-borderBox background, unchecked and checked.
--gog-checkbox-icon-colorCheckmark color.
--gog-checkbox-label-colorLabel text color.
--gog-checkbox-focus-ring / -focus-ring-width / -focus-ring-offsetKeyboard focus ring. The colour reads --gog-accent-color rather than the pale wash it used to, corrected in 21.12.0: this outline is the only thing marking focus on this control, and a wash measured 1.38:1 against the light page where WCAG asks for 3:1.