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.

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

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

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

I agree

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

Checked: false

Examples

Sizes

Five size steps, from xsm to slg.

@for (sizeOption of sizes; track sizeOption) {
  <gog-checkbox [size]="sizeOption" [label]="sizeOption" [checked]="true" />
}

Indeterminate — select all

indeterminate is purely presentational: a dash instead of the checkmark, plus aria-checked="mixed". Drive it yourself from the state of a group, as a "select all" checkbox does here.

Select all

Newsletter

Special offers

Product updates

<gog-checkbox
  label="Select all"
  [checked]="allChecked()"
  [indeterminate]="someChecked() && !allChecked()"
  (checkedChange)="setAll($event)"
/>

@for (item of subscriptions(); track item.id) {
  <gog-checkbox
    [label]="item.label"
    [checked]="item.checked"
    (checkedChange)="setOne(item.id, $event)"
  />
}

Disabled

Disabled blocks toggling in every check state.

Disabled, unchecked

Disabled, checked

Disabled, indeterminate

<gog-checkbox label="Disabled, unchecked" [disabled]="true" />
<gog-checkbox label="Disabled, checked" [checked]="true" [disabled]="true" />
<gog-checkbox label="Disabled, indeterminate" [indeterminate]="true" [disabled]="true" />

No visible label

Without label, set ariaLabel so the checkbox still has an accessible name — for example a row-selection checkbox in a table.

<gog-checkbox ariaLabel="Select row" [(checked)]="agreed" />

Full width

Stretches the row to fill its container; wrapped here in a narrower box to show it.

Full width row

<gog-checkbox label="Full width row" [fullWidth]="true" />

Reactive Forms

Works as a ControlValueAccessor — wire it to a FormControl with [formControl] or formControlName instead of [(checked)]. Don't bind both to the same instance.

Control value: false

<gog-checkbox label="Subscribe" [formControl]="control" />

Custom check icon

Project an <ng-template gogCheckboxIcon> to replace the checkmark drawn inside the box. This replaces the checkIconTemplate input, deprecated in 21.3.0 and removed in 21.5.0 — both work meanwhile, and the projected slot wins when a call site has both.

Custom mark

<gog-checkbox label="Custom mark" [checked]="true">
  <ng-template gogCheckboxIcon>
    <gog-icon name="close" />
  </ng-template>
</gog-checkbox>

API Reference

Inputs

Name	Type	Default	Description
`checked`	`boolean (model)`	`false`	Two-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.
`label`	`string`	`''`	Visible label rendered next to the box. Takes priority over ariaLabel when present.
`ariaLabel`	`string`	`''`	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.
`indeterminate`	`boolean`	`false`	Renders a dash instead of the checkmark and sets aria-checked="mixed", regardless of checked. Purely presentational — does not affect the underlying checked value.
`disabled`	`boolean`	`false`	Sets the native disabled attribute and blocks toggling. A FormControl.disable() has the same effect via setDisabledState.
`fullWidth`	`boolean`	`false`	Stretches the checkbox row to fill its container.
`checkIconTemplate`	`TemplateRef<unknown> \| null`	`null`	Deprecated since 21.3.0, removed in 21.5.0 — project an <ng-template gogCheckboxIcon> instead. Still works, and the projected slot wins when both are present.

Content slots

Slot	Description
`<ng-template gogCheckboxIcon>`	Replaces the checkmark drawn inside the box when checked. Wins over the deprecated `checkIconTemplate` input.

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.

Token	Description
`--gog-checkbox-gap`	Gap between box and label.
`--gog-checkbox-radius`	Box corner radius.
`--gog-checkbox-border-width / -style / -color`	Box border.
`--gog-checkbox-bg / -checked-bg / -checked-border`	Box background, unchecked and checked.
`--gog-checkbox-icon-color`	Checkmark color.
`--gog-checkbox-label-color`	Label text color.
`--gog-checkbox-focus-ring / -focus-ring-width / -focus-ring-offset`	Keyboard focus ring.