GUILD OF GLEKS UIv21.19.0

gog-toggle

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.

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

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

Basic usage — [(checked)] holds the state:

checked: true

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

Examples

Sizes and states

Off, on, and both disabled, in the five sizes — a switch has no third state, which is the first thing that separates it from a checkbox. The track and thumb have their own scale (--gog-toggle-<size>-*); only the label size is shared with gog-checkbox. Both states stay legible while disabled.

xsm
sm
md
lg
slg
@for (size of sizes; track size) {
  <div>
    <span>{{ size }}</span>
    <gog-toggle [size]="size" label="Off" />
    <gog-toggle [size]="size" label="On" [checked]="true" />
    <gog-toggle [size]="size" label="Disabled" disabled />
    <gog-toggle [size]="size" label="Disabled, on" disabled [checked]="true" />
  </div>
}

Labels inside the track

onLabel / offLabel render inside the track — the one thing a checkbox cannot do. Both stay in the DOM and the track sizes to the wider of the two, so its width cannot jump as the switch flips; the inactive one is faded, not removed. Keep them short, and do not put the state's meaning only there: they are aria-hidden, because the role already announces on and off.

<!-- Both labels stay in the DOM, so the track is as wide as the wider one. -->
<gog-toggle label="ON / OFF" onLabel="ON" offLabel="OFF" [checked]="true" />
<gog-toggle label="YES / NO" onLabel="YES" offLabel="NO" />
<gog-toggle label="Only one set" onLabel="LIVE" />
<gog-toggle size="slg" label="slg" onLabel="ON" offLabel="OFF" [checked]="true" />

Label position

The control is a <label> around the input, so its text is the accessible name and the whole row is the hit target. labelPosition="start" puts the text first — what a settings list wants, so the switches line up on one edge.

end (default)
start
<div>
  <span>end (default)</span>
  <gog-toggle label="Notifications" [checked]="true" />
</div>
<div>
  <span>start</span>
  <gog-toggle labelPosition="start" label="Notifications" [checked]="true" />
</div>

A settings list — full width

fullWidth fills the container — the dashed box here. With labelPosition="start" that is the row every settings screen is made of: label at one edge, switch at the other, the whole line pressable.

<!-- fullWidth + labelPosition="start": the label at one edge, the switch at the other. -->
<gog-toggle fullWidth labelPosition="start" label="Email notifications" [(checked)]="email" />
<gog-toggle
  fullWidth
  labelPosition="start"
  label="Share anonymous usage data"
  [(checked)]="telemetry"
/>
<gog-toggle fullWidth labelPosition="start" label="Beta features" disabled />

No visible label

ariaLabel names a switch when the row around it already says what it is — a table cell, a toolbar. It is the only case that input is for.

<!-- No visible label: ariaLabel names the switch when the row around it already says what it is. -->
<gog-toggle ariaLabel="Dark mode" [checked]="true" />
<gog-toggle ariaLabel="Compact rows" />

Two-way binding

A switch takes effect immediately — there is no Save button between the press and the setting, which is the behavioural half of the difference from a checkbox. That makes checkedChange the place to do the work.

checked: false · 0 checkedChange

<gog-toggle
  label="Dark mode"
  onLabel="ON"
  offLabel="OFF"
  [(checked)]="dark"
  (checkedChange)="changes.update((n) => n + 1)"
/>
<p>checked: {{ dark() }} · {{ changes() }} checkedChange</p>

Reactive forms

A ControlValueAccessor, so formControl / formControlName work directly: the form drives checked, and disabling through the form ends up as disabled on the native input.

value: true · touched: false · disabled: false

<div>
  <gog-toggle label="Auto-update" [formControl]="control" />
</div>

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

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

App-wide defaults — GOG_CONFIG

control.size sets the default size for every toggle under the provider; an instance's own input still wins. This example provides the config on itself so it reaches only its own toggles — in an app it goes in app.config.ts. See Global Configuration.

size unset
size="sm"
<div>
  <span>size unset</span>
  <gog-toggle label="Takes lg from the config" [checked]="true" />
</div>
<div>
  <span>size="sm"</span>
  <gog-toggle size="sm" label="The instance wins" [checked]="true" />
</div>

Toggle or checkbox?

A switch answers "is this setting on" and applies at once; a checkbox answers "is this one of the things you selected" and waits for the form around it. That is why this component has no indeterminate, no error line and no group: a list of switches is a list of independent settings, while a list of checkboxes is usually one answer made of several parts. Reach for Checkbox inside a form and for gog-toggle in a settings list.

Accessibility

The control is a real checkbox input with role="switch" — the only ARIA on it. The state is the input's own checked property, so there is no aria-checked, and Space, form submission and a :checked selector all keep working.

  • Keyboard — Tab reaches it, Space flips it.
  • Name — the label, or ariaLabel when there is no visible one.
  • Painting — the track, the thumb and the two track labels are aria-hidden; painting it differently is the entire difference from gog-checkbox.

API Reference

Inputs

NameTypeDefaultDescription
checkedbooleanfalseThe on/off state. Two-way bindable with [(checked)]. Drive this or a form directive, never both.
labelstring''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 / offLabelstring''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.
ariaLabelstring''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. The track and thumb have their own scale; the label size is shared with gog-checkbox.
disabledbooleanfalseBlocks interaction. A form control’s own disabled state is honoured too.
fullWidthbooleanfalseStretches the row to fill its container, pushing the switch and the label apart — the usual settings-list layout.

Outputs

NamePayloadDescription
checkedChangebooleanEmitted when the user flips the switch. Comes from the checked model input.

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 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.

TokenDescription
--gog-toggle-track-off-bg / -track-on-bg / -on-border-colorThe track, off and on.
--gog-toggle-border-color / -border-width / -border-styleThe track’s edge in the off state, which is the whole of the control when it is off. It defaults to --gog-control-boundary-color since 21.12.0; reading the decorative hairline instead had left an off switch at under 3:1 in all eleven themes, which is to say invisible to WCAG.
--gog-toggle-thumb-off-bg / -thumb-on-bg / -thumb-shadow / -thumb-insetThe sliding thumb.
--gog-toggle-{size}-track-width / -track-height / -thumb-size / -label-sizeFull sizing scale, per size step (xsm/sm/md/lg/slg).
--gog-toggle-state-color / -state-font-weight / -state-padding-inline / -state-thumb-gapThe onLabel / offLabel text rendered inside the track.
--gog-toggle-label-color / -gap / -radiusThe label next to the switch, its gap, and the track corner radius.
--gog-toggle-focus-ring-color / -focus-ring-width / -focus-ring-offset / -disabled-opacityKeyboard focus ring and the disabled state.