Select

Overview

Import the component and drop it into a template.

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

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

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

<gog-select label="Framework" [options]="frameworks" [(value)]="framework" />

Selected: None selected

Examples

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

<gog-select label="Disabled" [options]="frameworks" value="angular" [disabled]="true" />

<gog-select label="Plan (one option disabled)" [options]="plansWithDisabled" [(value)]="plan" />

<gog-select
  label="Required plan"
  placeholder="Choose a plan..."
  [options]="plansWithDisabled"
  [errorMessage]="requiredValue() === null ? 'Please pick a plan.' : ''"
  [(value)]="requiredValue"
/>

<gog-select
  label="Billing cycle"
  placeholder="Choose a cycle..."
  [options]="billingCycles"
  [formControl]="billingCycleControl"
  errorMessage="A billing cycle is required."
  errorDisplay="auto"
/>

<gog-select label="Country" [options]="countries" [(value)]="fullWidthCountry" />
<gog-select label="Currency" [options]="currencies" [(value)]="currency" [fullWidth]="false" />

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

<gog-select
  ariaLabel="Country (no visible label)"
  placeholder="Pick a country"
  [options]="countries"
  [(value)]="ariaOnlyValue"
/>

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

Your own objects

optionLabel, optionValue and optionDisabled each take a property path — dot-paths included — or a function. A real DTO goes straight in, with no mapping into { id, name } first and nothing lost on the way back out. The defaults are 'name' / 'id' / 'disabled', so code written before 21.3.0 is unaffected; GogDropdownOption is no longer a requirement, just the shape those defaults expect to find.

Set [optionValue]="null" and the control emits the option object itself — the same reference you passed in, not a copy.

<!-- A real DTO goes straight in: no mapping into { id, name } first. -->
<gog-select
  label="Assignee"
  optionLabel="profile.fullName"
  optionValue="uuid"
  optionDisabled="suspended"
  [options]="users"
  [(value)]="userId"
/>

<!-- [optionValue]="null" hands back the option object itself. -->
<gog-select
  label="Assignee (object)"
  optionLabel="profile.fullName"
  [optionValue]="null"
  [options]="users"
  [(value)]="userObject"
/>

Filtering

filter puts a search box in the panel, matching case-insensitively on the resolved optionLabel. The query resets when the panel closes, and filterPosition sticks the box to either end of the list. filterMatch swaps the default match for your own predicate — useful for searching a field the label never shows.

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-select-panel-radius and the filter reshapes itself to match.

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

<!-- filterMatch replaces the default substring match on the label. -->
<gog-select
  label="Assignee"
  optionLabel="profile.fullName"
  optionValue="uuid"
  [filter]="true"
  [filterMatch]="matchNameOrRole"
  [options]="users"
  [(value)]="userId"
/>

Clearable

The clear button is value-driven: it appears once something is selected and vanishes when nothing is. That is the point — it replaces the fake "— not selected —" option teams add to make a choice undoable. It takes the outermost trailing position, with the chevron shifting inward, so the trigger's width stays stable and the destructive control is not on the very edge.

<gog-select label="Plan" [clearable]="true" [options]="plansWithDisabled" [(value)]="plan" />

Custom option rows

A gogDropdownOption template replaces one option row. Its context carries the option itself plus selected, disabled and the already-resolved label — so a custom row can decorate the label rather than re-derive it.

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

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-checkbox label="virtualize the first field" [(checked)]="virtualizeOn" />
<gog-select
  label="City (windowed)"
  [options]="cities"
  [virtualize]="virtualizeOn()"
  [filter]="true"
  [(value)]="windowedCity"
/>
<gog-select
  label="City (eager, for comparison)"
  [options]="cities"
  [filter]="true"
  [(value)]="eagerCity"
/>

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