gog-button-toggle-group

Button Toggle

A row of buttons where one — or, with multiple, several — can be picked. Options-driven, taking your own objects through the same optionLabel / optionValue / optionDisabled accessors Select uses.

Overview

Import the component and drop it into a template.

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

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

Basic usage:

Selected: list

<gog-button-toggle-group ariaLabel="View" [options]="views" [(value)]="view" />

Single and multiple are different widgets

multiple is not a cosmetic switch. In single mode the group is a radio group — role="radiogroup" / role="radio" with aria-checked, and the arrow keys move and select, because that is what a radio group does. In multiple mode it is a toolbar of independent toggles — role="group" with aria-pressed, arrows only move, and Space toggles. Getting this backwards is the usual defect in this component; here it follows from the input.

Multiple

Active: bold

<gog-button-toggle-group
  ariaLabel="Text formatting"
  [options]="formats"
  [multiple]="true"
  [(value)]="activeFormats"
/>

Examples

Appearance and orientation

joined is one segmented control sharing borders; separated is discrete buttons with a gap. Either works vertically.

joined

separated

vertical

<gog-button-toggle-group appearance="joined" [options]="views" [(value)]="view" />
<gog-button-toggle-group appearance="separated" [options]="views" [(value)]="view" />

<!-- Vertical works with either appearance. -->
<gog-button-toggle-group orientation="vertical" [options]="views" [(value)]="view" />

Icons

optionIcon takes the same accessor shape as the other option inputs — a property path or a function.

<gog-button-toggle-group
  ariaLabel="View"
  optionIcon="icon"
  [options]="views"
  [(value)]="iconView"
/>

Custom button markup

A gogButtonToggleOption template replaces the button's content, with $implicit, selected and disabled in its context. The template's option arrives as unknown — the directive cannot see the group's TOption — so narrow it with a one-line helper, as below.

<gog-button-toggle-group [options]="views" [(value)]="slotView">
  <ng-template gogButtonToggleOption let-option let-selected="selected">
    <gog-icon [name]="asView(option).icon" />
    <span>{{ asView(option).name }}</span>
    @if (selected) {
      <gog-icon name="check" />
    }
  </ng-template>
</gog-button-toggle-group>

Sizes

Five steps, also settable app-wide through GOG_CONFIG.control.size.

@for (sizeOption of sizes; track sizeOption) {
  <gog-button-toggle-group [size]="sizeOption" [options]="views" [(value)]="sizeView" />
}

Accessibility

The roles and keyboard model follow multiple, as described above. Set ariaLabel on the group — the buttons alone ("List", "Grid") rarely say what is being chosen. Disabled options are skipped by arrow navigation rather than merely being unclickable.

API Reference

Inputs

Name	Type	Default	Description
`options`	`TOption[]`	`[]`	The buttons. Your own objects — nothing has to be mapped into a fixed shape.
`optionLabel`	`string \| ((o: TOption) => string)`	`'name'`	How an option turns into its button label: a property path (dot-paths included) or a function.
`optionValue`	`string \| ((o: TOption) => unknown) \| null`	`'id'`	How an option turns into the emitted value. Set it to null and the group emits the option object itself.
`optionDisabled`	`string \| ((o: TOption) => boolean)`	`'disabled'`	Which options are non-selectable.
`optionIcon`	`string \| ((o: TOption) => GogIconName \| null) \| null`	`null`	An optional leading icon per button.
`value`	`TValue \| TValue[] \| null`	`null`	The selection: one value, or an array when multiple is on. Two-way bindable with [(value)].
`multiple`	`boolean`	`false`	Several buttons can be active at once. This changes the widget’s semantics, not just its behaviour — see Accessibility.
`appearance`	`'joined' \| 'separated'`	`'joined'`	joined is one segmented control with shared borders; separated is discrete buttons with a gap.
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Which way the buttons stack.
`size`	`'xsm' \| 'sm' \| 'md' \| 'lg' \| 'slg'`	`GOG_CONFIG.control.size ?? 'md'`	Button padding and typography.
`disabled`	`boolean`	`false`	Disables the whole group.
`fullWidth`	`boolean`	`false`	Stretches the group so its buttons share the container’s width.
`ariaLabel`	`string`	`''`	Accessible name for the group. Worth setting — the buttons alone rarely say what the group is for.

Outputs

Name	Payload	Description
`valueChange`	`TValue \| TValue[] \| null`	Emitted when the selection changes. Comes from the value model input.

Content slots

Directive	Context	Description
`gogButtonToggleOption`	`$implicit, selected, disabled`	Replaces one button's content.

Styling Tokens

Every CSS custom property the group 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-button-toggle-rest-bg / -rest-color`	An unselected button.
`--gog-button-toggle-selected-bg / -selected-color / -selected-border-color`	The selected button.
`--gog-button-toggle-hover-bg / -hover-color`	Hover state.
`--gog-button-toggle-border-color / -border-width / -border-style / -radius`	Group border and corner radius.
`--gog-button-toggle-separated-gap`	Gap between buttons in the "separated" appearance. "joined" shares borders.
`--gog-button-toggle-font-family / -font-weight / -letter-spacing / -text-transform / -icon-size`	Button typography and icon size.
`--gog-button-toggle-focus-ring-color / -focus-ring-width / -focus-ring-offset`	Keyboard focus ring.