Multiselect

Overview

Import the component and drop it into a template.

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

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

Basic usage — a labeled field bound with [(value)]:

<gog-multiselect label="Features" [options]="features" [(value)]="selectedFeatures" />

Selected: None selected

Examples

<gog-multiselect #ms label="Tags" [options]="tags" [(value)]="fullWidthTags" />
<p>Selected: {{ ms.selectedNames() }}</p>

@for (sizeOption of sizes; track sizeOption) {
  <gog-multiselect [label]="'Size: ' + sizeOption" [size]="sizeOption" [options]="features" [(value)]="sizeDemoValue" />
}

<gog-multiselect
  label="Top (default)"
  [options]="countries"
  [showControls]="true"
  [(value)]="topControlsValue"
/>

<gog-multiselect
  label="Bottom"
  [options]="countries"
  [showControls]="true"
  controlsPosition="bottom"
  [(value)]="bottomControlsValue"
/>

<gog-multiselect label="Disabled" [options]="features" [value]="['toast']" [disabled]="true" />

<gog-multiselect label="Permissions (one disabled)" [options]="permissionsWithDisabled" [(value)]="permissions" />

<gog-multiselect
  label="Required tags"
  placeholder="Pick at least one..."
  [options]="permissionsWithDisabled"
  [errorMessage]="requiredError()"
  [(value)]="requiredValue"
/>

<gog-multiselect
  label="Permissions"
  placeholder="Pick at least one..."
  [options]="permissionsWithDisabled"
  [formControl]="permissionsFormControl"
  errorMessage="Pick at least one permission."
  errorDisplay="auto"
/>

<gog-multiselect label="Features" [options]="features" [(value)]="fullWidthFeatures" />
<gog-multiselect label="Tags" [options]="tags" [(value)]="fullWidthTags" [fullWidth]="false" />

<gog-multiselect [options]="sortOptions" [(value)]="sortValue">
  <ng-template gogDropdownChevron>
    <gog-icon name="sort" />
  </ng-template>
  <ng-template gogMultiselectClearIcon>
    <gog-icon name="error" />
  </ng-template>
</gog-multiselect>

<gog-multiselect
  ariaLabel="Tags (no visible label)"
  placeholder="Pick tags"
  [options]="tags"
  [(value)]="ariaOnlyValue"
/>

<gog-multiselect
  label="Country (fixed 240px / 160px panel)"
  [options]="countries"
  [appendToBody]="true"
  dropdownWidth="240px"
  dropdownMaxHeight="160px"
  [(value)]="compactPanelValue"
/>

Your own objects

The same accessors Select takes: optionLabel, optionValue and optionDisabled each accept a property path — dot-paths included — or a function. With [optionValue]="null" the control emits the option objects themselves. Defaults are 'name' / 'id' / 'disabled', so pre-21.3.0 code is unaffected.

<gog-multiselect
  label="Reviewers"
  optionLabel="profile.fullName"
  optionValue="uuid"
  optionDisabled="suspended"
  [options]="users"
  [(value)]="reviewerIds"
/>

Filtering

filter puts a search box in the panel. The important detail is what it does to "select all": that control takes only the visible options, so it means what it says while a filter is active rather than quietly selecting the whole list. The query resets when the panel closes.

The search box has square corners, and that is the concentric answer rather than a value clamped to zero. It is inset from the panel edge by exactly the panel's own radius, and at that distance the inner box's corner point sits on the centre of the panel's corner arc — a right angle there is equidistant from the whole curve, which is the only shape that keeps the gap constant. Override --gog-multiselect-panel-radius and the filter reshapes itself to match.

<gog-multiselect
  label="Country"
  [filter]="true"
  [showControls]="true"
  filterPlaceholder="Search countries…"
  filterEmptyMessage="No country matches"
  [options]="countries"
  [(value)]="selected"
/>

A long selection collapses to +N

The trigger shows what fits on one line and a count for the rest, with the full list in a tooltip. Select several of these and shrink the window to watch it re-measure: the available space changes when the container resizes, which Angular never renders for, so a ResizeObserver drives it rather than change detection.

Custom option rows

A gogDropdownOption template replaces one option row, with the option itself plus selected, disabled and the resolved label in its context. The per-option checkbox stays — it is the control's affordance, not part of the row's content.

<gog-multiselect
  label="Reviewers"
  optionLabel="profile.fullName"
  optionValue="uuid"
  [options]="users"
  [(value)]="reviewerIds"
>
  <ng-template gogDropdownOption let-user let-label="label">
    <strong>{{ label }}</strong>
    <small>{{ user.profile.role }}</small>
  </ng-template>
</gog-multiselect>

Virtualized options — virtualize21.13.0

[virtualize]="true" renders only the rows in view. Unwindowed, 10 000 options build 10 000 DOM rows to show about six — measured in Chrome, 512 ms before the panel appears, against 21 ms windowed on the same data. The scrollbar looks the same either way, because spacers stand in for the rows that are not there.

<gog-multiselect
  label="Cities"
  [options]="cities"
  [virtualize]="true"
  [filter]="true"
  [showControls]="true"
  [(value)]="windowedCities"
/>

Off by default, and never switched on at some row count. A windowed list behaves differently in ways nothing about the data predicts: Ctrl+F finds only the rendered rows, and CSS targeting :last-child matches the last rendered row. A threshold would make that depend on how much data happened to arrive, so set it per field, or app-wide with GOG_CONFIG.dropdown.virtualize.

• The announced count stays honest: the aria-setsize and aria-posinset carry the real list, so a screen reader hears "10 000 items" rather than "20". Arrow keys walk the whole list — End reaches the last option.
• Scrolling a keyboard-focused row out of view hands focus back to the trigger, because the row it was on no longer exists. Escape and ArrowDown both work from there. A plain list never has to do this.
• gog-table's virtualize is a different story under the same name: table rows vary in height, so it measures as it goes — see the Table page.

API Reference

Inputs

Content slots

Styling Tokens

Every CSS custom property the multiselect 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.