GUILD OF GLEKS UIv21.19.0

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.

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

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

Basic usage — [(value)] holds the selected option's id, and an option with disabled: true cannot be picked:

Selected: list

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

Examples

Appearance and orientation

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

joined
separated
vertical
<div>
  <span>joined</span>
  <gog-button-toggle-group ariaLabel="Align" [options]="alignments" [(value)]="align" />
</div>
<div>
  <span>separated</span>
  <gog-button-toggle-group
    appearance="separated"
    ariaLabel="Align"
    [options]="alignments"
    [(value)]="align"
  />
</div>

<!-- Vertical works with either appearance. -->
<div>
  <span>vertical</span>
  <gog-button-toggle-group
    orientation="vertical"
    ariaLabel="Align"
    [options]="alignments"
    [(value)]="align"
  />
  <gog-button-toggle-group
    orientation="vertical"
    appearance="separated"
    ariaLabel="Align"
    [options]="alignments"
    [(value)]="align"
  />
</div>

Sizes

Five steps, in both appearances — also settable app-wide through GOG_CONFIG.control.size (see the last example).

xsm
sm
md
lg
slg
@for (size of sizes; track size) {
  <div>
    <span>{{ size }}</span>
    @for (appearance of appearances; track appearance) {
      <gog-button-toggle-group
        [size]="size"
        [appearance]="appearance"
        ariaLabel="Align"
        [options]="alignments"
        value="center"
      />
    }
  </div>
}

States

Nothing selected, one selected, a single option disabled through optionDisabled, and the whole group disabled — then the multiple mode with none and all of its options on. A disabled option stays in place and is skipped by the arrow keys rather than merely being unclickable.

no value
selected
one option disabled
group disabled
multiple, none
multiple, all
<div>
  <span>no value</span>
  <gog-button-toggle-group ariaLabel="Align" [options]="alignments" />
</div>
<div>
  <span>selected</span>
  <gog-button-toggle-group ariaLabel="Align" [options]="alignments" value="center" />
</div>

<!-- optionDisabled reads `disabled` off each option by default. -->
<div>
  <span>one option disabled</span>
  <gog-button-toggle-group ariaLabel="Align" [options]="oneDisabled" value="left" />
</div>
<div>
  <span>group disabled</span>
  <gog-button-toggle-group ariaLabel="Align" [options]="alignments" value="left" disabled />
</div>

<div>
  <span>multiple, none</span>
  <gog-button-toggle-group ariaLabel="Tools" [options]="tools" multiple [value]="[]" />
</div>
<div>
  <span>multiple, all</span>
  <gog-button-toggle-group
    ariaLabel="Tools"
    [options]="tools"
    multiple
    [value]="['search', 'filter', 'star']"
  />
</div>

Icons

optionIcon takes the same accessor shape as the other option inputs — a property path or a function — and draws a leading icon on each button.

<!-- optionIcon is an accessor, like optionLabel: a property path or a function. -->
<gog-button-toggle-group
  ariaLabel="Tools"
  optionIcon="icon"
  [options]="tools"
  multiple
  [(value)]="active"
/>

Custom button markup

A gogButtonToggleOption template replaces the button's content, with $implicit, selected, disabled and the resolved label in its context. Bind [gogButtonToggleOptionTypeOf] to the same array as options21.15.0 and the option is typed as its element — option.icon below is checked under strictTemplates. The binding is never read at runtime; left unbound, the option is unknown, as before.

custom content
icon only
<div>
  <span>custom content</span>
  <gog-button-toggle-group ariaLabel="View" [options]="tools" [(value)]="view">
    <!-- [gogButtonToggleOptionTypeOf] types `option` from the array it renders. -->
    <ng-template
      gogButtonToggleOption
      [gogButtonToggleOptionTypeOf]="tools"
      let-option
      let-selected="selected"
    >
      <gog-icon [name]="option.icon" />
      <span>{{ option.name }}</span>
      @if (selected) {
        <gog-icon name="check" />
      }
    </ng-template>
  </gog-button-toggle-group>
</div>

<!-- Icon only: the resolved label stays in the button as visually hidden text. -->
<div>
  <span>icon only</span>
  <gog-button-toggle-group ariaLabel="Tools" [options]="tools" multiple [(value)]="active">
    <ng-template
      gogButtonToggleOption
      [gogButtonToggleOptionTypeOf]="tools"
      let-option
      let-label="label"
    >
      <gog-icon [name]="option.icon" />
      <span class="gog-visually-hidden">{{ label }}</span>
    </ng-template>
  </gog-button-toggle-group>
</div>

The icon-only group keeps each button's name: label goes into the button as text hidden with the library's gog-visually-hidden class, so a screen reader still hears "Search", "Filter", "Star".

Full width

fullWidth stretches the group to its container — the dashed box here — and the buttons share the width.

<gog-button-toggle-group
  ariaLabel="Align"
  [options]="alignments"
  value="center"
  size="sm"
  fullWidth
/>

Two-way binding and forms

value is a model, so [(value)] works in both modes and valueChange fires on every pick. The group is also a ControlValueAccessor: a formControl drives it, and disabling the control disables the group.

[(value)]left · 0 valueChange
formControlright
<div>
  <span>[(value)]</span>
  <gog-button-toggle-group
    ariaLabel="Align"
    [options]="alignments"
    [(value)]="align"
    (valueChange)="changes.update((n) => n + 1)"
  />
  <code>{{ align() }} · {{ changes() }} valueChange</code>
</div>

<!-- A ControlValueAccessor: formControl, and the control's disabled state, work as on any input. -->
<div>
  <span>formControl</span>
  <gog-button-toggle-group ariaLabel="Align" [options]="alignments" [formControl]="control" />
  <gog-button variant="outline" size="sm" (gogClick)="toggleDisabled()">
    {{ control.disabled ? 'enable()' : 'disable()' }}
  </gog-button>
  <code>{{ control.value }}</code>
</div>

App-wide defaults — GOG_CONFIG

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

size unset
size="sm"
<div>
  <span>size unset</span>
  <gog-button-toggle-group ariaLabel="Align" [options]="alignments" value="center" />
</div>
<div>
  <span>size="sm"</span>
  <gog-button-toggle-group ariaLabel="Align" [options]="alignments" value="center" size="sm" />
</div>

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 or Enter toggles. Getting this backwards is the usual defect in this component; here it follows from the input. With multiple, value is an array.

Active: bold

<!-- multiple: a toolbar of independent toggles, and value is an array. -->
<gog-button-toggle-group
  ariaLabel="Text formatting"
  [options]="formats"
  multiple
  [(value)]="active"
/>
<p>Active: {{ active().join(', ') || 'none' }}</p>

Accessibility

The roles follow multiple, as described above. The group is one tab stop: Tab lands on the selected option, or on the first enabled one when nothing is selected.

  • Single mode — the arrow keys move to the next enabled option and select it.
  • Multiple mode — the arrow keys move focus only; Space or Enter toggles the focused option.
  • Disabled — a disabled option is skipped by the arrows; a disabled group is out of the tab order.
  • Name — set ariaLabel on the group: the buttons alone ("List", "Grid") rarely say what is being chosen. An icon-only button needs its label kept as hidden text, as in Custom button markup.

API Reference

Inputs

NameTypeDefaultDescription
optionsreadonly TOption[][]The buttons. Your own objects — nothing has to be mapped into a fixed shape.
optionLabelstring | ((o: TOption) => string)'name'How an option turns into its button label: a property path (dot-paths included) or a function.
optionValuestring | ((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.
optionDisabledstring | ((o: TOption) => boolean)'disabled'Which options are non-selectable.
optionIconstring | ((o: TOption) => GogIconName | null) | nullnullAn optional leading icon per button.
valueTValue | TValue[] | nullnullThe selection: one value, or an array when multiple is on. Two-way bindable with [(value)].
multiplebooleanfalseSeveral 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.
disabledbooleanfalseDisables the whole group.
fullWidthbooleanfalseStretches the group so its buttons share the container’s width.
ariaLabelstring''Accessible name for the group. Worth setting — the buttons alone rarely say what the group is for.
rippleboolean | undefinedundefinedPress 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

NamePayloadDescription
valueChangeTValue | TValue[] | nullEmitted when the selection changes. Comes from the value model input.

Content slots

DirectiveContextDescription
gogButtonToggleOption$implicit, selected, disabled, labelReplaces one button's content. label is the resolved label, for hidden text or decoration.
[gogButtonToggleOptionTypeOf]21.15.0readonly TOption[] — an input on gogButtonToggleOptionBind the same array as options and $implicit is typed as its element instead of unknown. Never read at runtime; left unbound, the template compiles exactly as before.

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.

TokenDescription
--gog-button-toggle-rest-bg / -rest-colorAn unselected button.
--gog-button-toggle-selected-bg / -selected-color / -selected-border-colorThe selected button.
--gog-button-toggle-hover-bg / -hover-colorHover state.
--gog-button-toggle-press-bg / -selected-press-bgPress 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 / -radiusGroup 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-gapGap between buttons in the "separated" appearance. "joined" shares borders.
--gog-button-toggle-font-family / -font-weight / -letter-spacing / -text-transform / -icon-sizeButton typography and icon size.
--gog-button-toggle-focus-ring-color / -focus-ring-width / -focus-ring-offsetKeyboard focus ring.