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.
`ripple`21.6.1	`boolean \| undefined`	`undefined`	Press ripple on each toggle in the group. Unset, falls back to GOG_CONFIG.ripple.enabled, which is off by default; setting it here wins over the app-wide value in both directions.

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.

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
GOG_CONFIG.ripple.enabled

This site is not on the default here. The library ships ripple.enabled as false; these docs set it to true app-wide so the demos above actually show the press feedback. In a fresh app you get no ripple until you ask for one — the droplet button in the header switches this site between the two, and it is on right now.

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-press-bg / -selected-press-bg`	Press state, with its own value for a button that is already selected — pressing one has to read as a press rather than as a deselection.
`--gog-button-toggle-border-color / -border-width / -border-style / -radius`	Group border and corner radius. The colour defaults to --gog-control-boundary-color since 21.12.0 — it read the decorative hairline before, which is why a segmented control now shows a visibly firmer edge in every theme.
`--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.