Toggle

An on/off switch: a native <input type="checkbox"> carrying role="switch", so it announces as "switch, on" rather than "checkbox, checked" while the platform keeps owning the keyboard and forms.

Overview

Import the component and drop it into a template.

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

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

Basic usage:

Notifications

<gog-toggle label="Notifications" [(checked)]="notifications" />

Toggle or checkbox?

A checkbox answers "is this one of the things you selected" and is usually submitted with a form. A switch answers "is this setting on", takes effect immediately, and is announced differently. Reach for Checkbox inside a form and for gog-toggle in a settings list.

Examples

Labels inside the track

onLabel / offLabel render inside the track itself. Both stay in the DOM and the track sizes to the wider of the two, so its width cannot jump as the switch flips.

Analytics

<gog-toggle label="Analytics" onLabel="ON" offLabel="OFF" [(checked)]="analytics" />

Sizes

Five steps, shared with gog-checkbox. Also settable app-wide through GOG_CONFIG.control.size.

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

Label placement and full width

labelPosition moves the label to the other side. fullWidth stretches the row so the switch lands on the far edge — the usual settings-list layout.

Label after the switch

Label before it

Full width

<gog-toggle label="Label after the switch" [(checked)]="compactMode" />
<gog-toggle label="Label before it" labelPosition="start" [(checked)]="labelStart" />

<!-- The settings-row layout: the switch is pushed to the far edge. -->
<gog-toggle label="Full width" [fullWidth]="true" [(checked)]="compactMode" />

Reactive forms

A ControlValueAccessor, so formControl / formControlName work directly — including the control's own disabled state.

Dark mode

Control value: true

<gog-toggle label="Dark mode" [formControl]="darkMode" />

Disabled

Both states stay legible while non-interactive.

Disabled, off

Disabled, on

<gog-toggle label="Disabled, off" [disabled]="true" />
<gog-toggle label="Disabled, on" [disabled]="true" [checked]="true" />

Accessibility

The control is a real checkbox input with role="switch", so Space toggles it, Tab reaches it, and it participates in a native form — only the announcement and the painting differ. Give it either a label or an ariaLabel; the track labels are aria-hidden, since the switch's own state is already announced.

API Reference

Inputs

Name	Type	Default	Description
`checked`	`boolean`	`false`	The on/off state. Two-way bindable with [(checked)]. Drive this or a form directive, never both.
`label`	`string`	`''`	Visible text label rendered next to the switch, inside the same <label>.
`labelPosition`	`'start' \| 'end'`	`'end'`	Which side of the switch the label sits on.
`onLabel / offLabel`	`string`	`''`	Short text rendered inside the track — the one thing a checkbox cannot do. Both stay in the DOM so the track width cannot jump as it flips; it sizes to the wider of the two.
`ariaLabel`	`string`	`''`	Accessible name, used when there is no visible label.
`size`	`'xsm' \| 'sm' \| 'md' \| 'lg' \| 'slg'`	`GOG_CONFIG.control.size ?? 'md'`	Track, thumb and label scale. Shares gog-checkbox’s size steps.
`disabled`	`boolean`	`false`	Blocks interaction. A form control’s own disabled state is honoured too.
`fullWidth`	`boolean`	`false`	Stretches the row to fill its container, pushing the switch and the label apart — the usual settings-list layout.

Outputs

Name	Payload	Description
`checkedChange`	`boolean`	Emitted when the user flips the switch. Comes from the checked model input.

Styling Tokens

Every CSS custom property the toggle 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-toggle-track-off-bg / -track-on-bg / -on-border-color`	The track, off and on.
`--gog-toggle-thumb-off-bg / -thumb-on-bg / -thumb-shadow / -thumb-inset`	The sliding thumb.
`--gog-toggle-{size}-track-width / -track-height / -thumb-size / -label-size`	Full sizing scale, per size step (xsm/sm/md/lg/slg).
`--gog-toggle-state-color / -state-font-weight / -state-padding-inline / -state-thumb-gap`	The onLabel / offLabel text rendered inside the track.
`--gog-toggle-label-color / -gap / -radius`	The label next to the switch, its gap, and the track corner radius.
`--gog-toggle-focus-ring-color / -focus-ring-width / -focus-ring-offset / -disabled-opacity`	Keyboard focus ring and the disabled state.