GUILD OF GLEKS UIv21.19.0

gog-select

Select

A single-choice dropdown over your own objects: a button trigger, a listbox panel that can filter, virtualize and escape a clipping container, and full ControlValueAccessor support. For several choices see Multiselect; for a typed query, see Autocomplete.

Overview

Import the component and drop it into a template.

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

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

Basic usage — [(value)] holds the selected option's id:

value: angular · 0 valueChange
<div>
  <gog-select
    label="Framework"
    placeholder="Pick a framework"
    [options]="frameworks"
    [(value)]="framework"
    (valueChange)="changes.update((n) => n + 1)"
  />
  <!-- The value is the option's id, through the default optionValue: 'id'. -->
  <code>value: {{ framework() ?? 'null' }} · {{ changes() }} valueChange</code>
</div>

Examples

Sizes

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

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

States

Empty, holding a value, disabled and with an error. With the default errorDisplay="manual" the message shows for as long as errorMessage is non-empty — the timing is yours; see Reactive forms below for the automatic kind.

Required field
<gog-select label="Value unset" placeholder="Pick a framework" [options]="frameworks" />
<gog-select label="Holding a value" [options]="frameworks" value="angular" />
<gog-select label="Disabled" [options]="frameworks" value="angular" disabled />
<gog-select
  label="Error"
  placeholder="Pick a framework"
  [options]="frameworks"
  errorMessage="Required field"
/>

Clearable

The clear button appears only once something is selected, so a field no longer needs a fake "— not selected —" option to make a choice undoable. It takes the outermost trailing position and the chevron shifts inward. It is the one part of the trigger that is not the trigger: a button inside a button is invalid HTML, so it is a sibling laid over the trigger's end edge, named by clearAriaLabel. Off by default here — Multiselect is the one control where it is on.

<!-- The clear button shows only while something is selected. -->
<gog-select label="clearable, with a value" [options]="frameworks" value="angular" clearable />
<gog-select
  label="clearable, empty"
  placeholder="Pick a framework"
  [options]="frameworks"
  clearable
/>
<gog-select
  label="clearAriaLabel"
  [options]="frameworks"
  value="vue"
  clearable
  clearAriaLabel="Clear framework"
/>
<gog-select label="clearable, disabled" [options]="frameworks" value="angular" clearable disabled />

Width

A field fills its container by default — the dashed box here. With [fullWidth]="false" the trigger sizes to whatever is selected, so a short option collapses it; minWidth is the floor under that.

<gog-select label="fullWidth (default)" [options]="frameworks" value="angular" />
<!-- Sizes to the selected label, so a short option collapses it. -->
<gog-select label='[fullWidth]="false"' [fullWidth]="false" [options]="frameworks" value="vue" />
<gog-select
  label='[fullWidth]="false" minWidth="12rem"'
  [fullWidth]="false"
  minWidth="12rem"
  [options]="frameworks"
  value="vue"
/>

Custom chevron, and no visible label

gogDropdownChevron replaces the chevron. The library turns only its own; a custom one gets let-open21.15.0 and draws the state itself — open the first field to watch the glyph change. ariaLabel names a field that has no label.

<!-- The library turns only its own chevron; a custom one draws its state from open. -->
<gog-select label="Chevron slot" [options]="sortOrders" value="newest">
  <ng-template gogDropdownChevron let-open>
    <gog-icon [name]="open ? 'sort-up' : 'sort'" />
  </ng-template>
</gog-select>

<gog-select
  ariaLabel="Framework (no visible label)"
  placeholder="Pick a framework"
  [options]="frameworks"
/>

Your own objects

optionLabel, optionValue and optionDisabled each take a property path — dot-paths included — or a function, so a real DTO goes in with no mapping into { id, name } first. [optionValue]="null" makes the value the option object itself, the same reference that went in. A gogDropdownOption template replaces one row, and its context carries the resolved label; [gogDropdownOptionTypeOf]21.15.0 types the option, so a typo in option.profile.role fails the build.

value: u1
value: null (the object)
<!-- Property paths, dot-paths included: a DTO goes in unmapped. -->
<div>
  <gog-select
    label="Reviewer (by uuid)"
    [options]="members"
    optionLabel="profile.fullName"
    optionValue="uuid"
    optionDisabled="suspended"
    [(value)]="memberId"
  />
  <code>value: {{ memberId() ?? 'null' }}</code>
</div>

<!-- A function label and [optionValue]="null": the value is the option object itself. -->
<div>
  <gog-select
    label="Reviewer (whole object)"
    placeholder="Pick someone"
    [options]="members"
    [optionLabel]="fullName"
    [optionValue]="null"
    [(value)]="member"
  >
    <!-- [gogDropdownOptionTypeOf] types `option` as a Member. -->
    <ng-template gogDropdownOption [gogDropdownOptionTypeOf]="members" let-option let-label="label">
      {{ label }} — <em>{{ option.profile.role }}</em>
    </ng-template>
  </gog-select>
  <code>value: {{ member()?.uuid ?? 'null' }} (the object)</code>
</div>

A disabled option

optionDisabled defaults to the disabled property, so a GogDropdownOption carrying it needs no binding. The row stays in the list, is announced as disabled, and neither the pointer nor the keyboard selects it.

value: free
<div>
  <gog-select label="Plan" [options]="plans" [(value)]="plan" />
  <code>value: {{ plan() ?? 'null' }}</code>
</div>

Filtering

filter puts a search box in the panel — worth it past about seven options, or order them instead, since a list the reader can predict is one they search rather than choose from. The default matcher is a case-insensitive substring of the resolved label; filterMatch swaps in any predicate. The query resets when the panel closes. The search box has square corners, and that is the concentric answer: inset from the panel edge by exactly the panel's radius, its corner sits on the centre of the panel's corner arc, the one shape that keeps the gap constant. Override --gog-select-panel-radius and it reshapes to match.

<gog-select label="filter" placeholder="Pick a country" [options]="countries" filter clearable />
<gog-select
  label='filterPosition="bottom"'
  placeholder="Pick a country"
  [options]="countries"
  filter
  filterPosition="bottom"
  filterPlaceholder="Type to search…"
/>
<gog-select
  label="filterMatch: prefix only"
  placeholder="Pick a country"
  [options]="countries"
  filter
  [filterMatch]="startsWith"
  filterEmptyMessage="No country starts with that"
/>

Direction

'auto' measures the room under the trigger and flips up when there is not enough; 'down' and 'up' are fixed, whatever the viewport does.

<gog-select label="dropdownDirection unset (auto)" [options]="frameworks" />
<gog-select label='dropdownDirection="down"' [options]="frameworks" dropdownDirection="down" />
<gog-select label='dropdownDirection="up"' [options]="frameworks" dropdownDirection="up" />

The panel — appendToBody

The panel renders inline by default and is clipped by any scrolling or overflow: hidden ancestor; open the first two — only the appended one survives its box. dropdownWidth and dropdownMaxHeight take any CSS length and apply only while the panel is appended: the third holds 20 options in 160px, so it scrolls.

<!-- Each box clips its content, as an overflow: hidden card or a scroller does. -->
<div style="overflow: hidden; padding: 12px; border: 1px dashed var(--gog-border-color)">
  <gog-select label="Inline panel (clipped)" [options]="countries" dropdownDirection="down" />
</div>
<div style="overflow: hidden; padding: 12px; border: 1px dashed var(--gog-border-color)">
  <gog-select
    label="appendToBody (escapes)"
    [options]="countries"
    dropdownDirection="down"
    appendToBody
  />
</div>
<div>
  <gog-select
    label="Panel 220px wide, 160px tall"
    [options]="countries"
    appendToBody
    dropdownWidth="220px"
    dropdownMaxHeight="160px"
  />
</div>

Virtualized options — virtualize

Both fields hold 10 000 options. Open each and compare how long the panel takes to appear: the windowed one keeps about twenty rows in the DOM, the eager one builds all 10 000 to show six — measured in Chrome, 512 ms against 21 ms. The scrollbar looks the same either way, because spacers stand in for the missing rows.

<gog-select label="virtualize" placeholder="Pick a city" [options]="cities" virtualize filter />
<gog-select label="Eager (default)" placeholder="Pick a city" [options]="cities" filter />

Off by default, and never switched on at a row count.Ctrl+F finds only the rendered rows, and CSS targeting :last-child matches the last rendered one; a threshold would make that depend on how much data arrived. Set it per field, or app-wide with GOG_CONFIG.dropdown.virtualize. The announced count stays honest — aria-setsize carries the real list — and scrolling a focused row out of view hands focus back to the trigger, since the row no longer exists. gog-table's virtualize works differently under the same name: see the Table page.

Float label

'none' keeps the label above the field; 'in', 'on' and 'over' rest it inside the trigger until focus or a selection moves it clear — each shown empty, then with a value. floatLabelShowPlaceholder brings the placeholder back under the floated label.

@for (variant of variants; track variant) {
  <gog-select
    [floatLabel]="variant"
    [label]="'floatLabel: ' + variant"
    placeholder="e.g. Angular"
    [options]="frameworks"
  />
  <gog-select
    [floatLabel]="variant"
    [label]="'floatLabel: ' + variant"
    [options]="frameworks"
    value="angular"
  />
}

<!-- The placeholder shows under the floated label once it has somewhere to float to. -->
<gog-select
  floatLabel="over"
  floatLabelShowPlaceholder
  label="floatLabelShowPlaceholder"
  placeholder="e.g. Angular"
  [options]="frameworks"
/>

Reactive forms

With errorDisplay="auto" the error shows once the control is touched and invalid — open the panel and close it without choosing — instead of the page computing when to pass an errorMessage. A choice clears it.

value: null · touched: false · disabled: false
<div>
  <gog-select
    label="Framework (reactive form)"
    placeholder="Pick a framework"
    [options]="frameworks"
    [formControl]="control"
    errorMessage="Required"
    errorDisplay="auto"
  />
  <div>
    <gog-button variant="outline" size="sm" (gogClick)="control.markAsTouched()">
      markAsTouched()
    </gog-button>
    <gog-button variant="outline" size="sm" (gogClick)="toggleDisabled()">
      {{ control.disabled ? 'enable()' : 'disable()' }}
    </gog-button>
  </div>
  <code>
    value: {{ control.value ?? 'null' }} · touched: {{ control.touched }} · disabled:
    {{ control.disabled }}
  </code>
</div>

App-wide defaults — GOG_CONFIG

control.size, control.clearable, dropdown.filter and floatLabel.variant set the defaults for every field under the provider; an instance's own input still wins. Open the third field for the filter. In an app the provider goes in app.config.ts — see Global Configuration.

<gog-select label="Size from the config (lg)" [options]="frameworks" />
<gog-select label='size="sm" — the instance wins' size="sm" [options]="frameworks" />
<!-- clearable, dropdown.filter and the float label come from the config: open it. -->
<gog-select label="Clearable, filter, float label" [options]="frameworks" value="angular" />

Accessibility

The trigger is a native <button>, not a <select>, carrying aria-haspopup="listbox", aria-expanded and aria-controls; the panel is a role="listbox" of role="option" rows with aria-selected and aria-disabled. The panel exists only while it is open.

  • Keyboard — on the trigger, Enter or Space opens and closes the panel; while it is open ↓ / ↑ move into the list on the first or last option. In the list the arrows move, wrap and skip disabled options, Home/End jump to the ends, Enter or Space selects, Esc closes and returns focus to the trigger, and Tab closes and moves on from the trigger — so an appended panel does not send focus to the end of the document. The list is one tab stop. Inside a dialog, Escape closes the list first and the dialog on the next press.
  • Name — the label through aria-labelledby, because a button is not a labelable element and for would be ignored. Without a label, ariaLabel, then the placeholder. The clear button is named by clearAriaLabel.
  • Error — aria-invalid on the trigger and an aria-describedby pointing at the message, which is a role="alert".
  • Virtualized — aria-setsize and aria-posinset carry the real list, so a screen reader hears "10 000 items", not "20".

API Reference

Inputs

NameTypeDefaultDescription
valueTValue | null (model)nullTwo-way bindable via [(value)]: the selected option run through optionValue — its id by default, the object itself with [optionValue]="null". Also driven by Angular Forms through writeValue/registerOnChange when used with formControlName/[formControl]/ngModel.
labelstring''Field label.
ariaLabelstring''Accessible name for the field when there is no visible label.
inputIdstring''id on the trigger button, and target of the label's for attribute.
placeholderstring'Select...'Text shown while no option is selected.
optionsreadonly TOption[][]The list of choices — your own objects. GogDropdownOption ({ id, name, disabled? }) is just the shape the default accessors expect, not a requirement.
optionLabelstring | ((o: TOption) => string)'name'How an option turns into its visible text: a property path (dot-paths included, "profile.fullName") or a function.
optionValuestring | ((o: TOption) => unknown) | null'id'How an option turns into the emitted value. Set it to null and the control emits the option OBJECT itself — the same reference you passed in.
optionDisabledstring | ((o: TOption) => boolean)'disabled'Which options cannot be picked.
clearablebooleanGOG_CONFIG.control.clearable ?? falseAdds a clear button in the outermost trailing position, with the chevron shifting inward when it appears. It shows only once something is selected — which is what removes the need for a fake "— not selected —" option just to make a choice undoable.
clearAriaLabelstring'Clear selection'Accessible name for that clear button.
filterbooleanGOG_CONFIG.dropdown.filter ?? falsePuts a search box in the panel, matching case-insensitively on the resolved optionLabel. The query resets when the panel closes.
filterPosition'top' | 'bottom'GOG_CONFIG.dropdown.filterPosition ?? 'top'Which end of the panel the search box sticks to. It carries a divider on the side facing the list, so it reads as chrome rather than as a row.
filterPlaceholder / filterEmptyMessagestring'Search...' / 'No matches'Wording for the search box and for the empty result.
filterMatch((option: TOption, query: string) => boolean) | nullnullReplaces the default case-insensitive substring match — for searching a field the label does not show, or for fuzzy matching.
floatLabel'none' | 'in' | 'on' | 'over'GOG_CONFIG.floatLabel.variant ?? 'none'Rests the label inside the field like a placeholder and floats it up once something is selected or the field has focus.
floatLabelShowPlaceholderbooleanGOG_CONFIG.floatLabel.showPlaceholder ?? falseReveals the placeholder once the label has floated out of the way.
errorMessagestring''Error text to display. Visibility is governed by errorDisplay.
errorDisplay'auto' | 'manual'GOG_CONFIG.control.errorDisplay ?? 'manual''manual': shown for as long as errorMessage is non-empty — you decide the timing. 'auto': shown once the attached FormControl is touched and invalid; falls back to manual without one.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg'GOG_CONFIG.control.size ?? 'md'Field height, padding, and font size.
disabledbooleanfalseDisables the trigger and closes the panel if it is open.
fullWidthbooleantrueFills its container by default. Set false to shrink to fit the selected label instead.
minWidthstring | nullnull (--gog-select-min-width, 120px)Floor for an auto-width trigger, any CSS length — so a short selection cannot collapse the field to its own chrome.
dropdownDirection'auto' | 'up' | 'down'GOG_CONFIG.dropdown.direction ?? 'auto'Which side the panel opens on. 'auto' flips to whichever side has room in the viewport.
dropdownZIndexnumber | nullnullExplicit stacking order for the panel. Left unset it falls back to the --gog-dropdown-z token.
dropdownWidthstring | nullnullFixed panel width, any CSS length. Applies only with appendToBody. Left unset, the panel sizes to its own content with the trigger width as a floor, capped by --gog-{select,multiselect}-panel-max-width — so picking a short option no longer cuts the longer ones off the list.
dropdownMaxHeightstring | nullnullFixed panel max-height, any CSS length. Applies only with appendToBody.
appendToBodybooleanGOG_CONFIG.dropdown.appendToBody ?? falsePortals the panel into document.body instead of rendering it inline — escapes an ancestor's scroll/overflow clipping. Worth setting app-wide for a layout whose dropdowns generally live inside scrollable containers.
rippleboolean | undefinedundefinedPress ripple on each option row in the panel. 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.
virtualizeboolean | undefinedGOG_CONFIG.dropdown.virtualize ?? falseRenders only the option rows in view — about twenty in the DOM whatever the list holds. Off by default and never switched on at a row count: Ctrl+F finds only rendered rows and :last-child matches the last rendered one. aria-setsize/aria-posinset keep the announced count real.

Outputs

NamePayloadDescription
valueChangeTValue | nullEmitted when the selection changes — a pick, the clear button, or a forms write. Comes from the value model input.

Content slots

DirectiveContextDescription
gogDropdownOption$implicit, selected, disabled, labelReplaces one option row. label is the resolved label, so a custom row can decorate it rather than re-derive it.
[gogDropdownOptionTypeOf]21.15.0readonly TOption[] — an input on gogDropdownOptionBind 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.
gogDropdownChevron21.15.0$implicit / openReplaces the trigger chevron. The library turns only its own; a custom one draws its state from open.

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.control.errorDisplay
  • GOG_CONFIG.control.clearable
  • GOG_CONFIG.floatLabel.variant
  • GOG_CONFIG.floatLabel.showPlaceholder
  • GOG_CONFIG.dropdown.appendToBody
  • GOG_CONFIG.dropdown.direction
  • GOG_CONFIG.dropdown.virtualize
  • GOG_CONFIG.dropdown.filter
  • GOG_CONFIG.dropdown.filterPosition
  • GOG_CONFIG.ripple.enabled — on the panel’s options
  • GOG_CONFIG.labels.clearSelection

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

TokenDescription
--gog-select-label-color / -label-font-family / -label-font-size / -label-font-weight / -label-letter-spacing / -label-line-height / -label-text-transformField label. Each aliases its --gog-field-label-* counterpart.
--gog-select-field-bg / -field-borderField surface and border.
--gog-select-radiusThe field’s corner radius — the field only. Until 21.12.0 it shaped the dropdown panel too, so rounding the trigger into a pill rounded the overlay into one as well; that box has its own token now.
--gog-select-focus-border / -focus-ringFocus state.
--gog-select-panel-bg / -panel-shadow / -panel-max-widthDropdown panel surface, and the cap on a panel that sizes to its own content rather than to the trigger.
--gog-select-panel-gapGap between the trigger and the panel. It was --gog-select-panel-offset until 21.13.0, and the old name stopped resolving in 21.14.0.
--gog-select-option-heightA seed for the first frame, not the row height: the component measures a real row and corrects itself, which is also what decides whether the panel opens up or down.
--gog-select-panel-radiusThe panel’s own corner, new in 21.12.0 and defaulting to var(--gog-radius), so nothing moves unless you change it. gog-autocomplete and gog-datepicker already declared theirs; this and the multiselect’s are the pair that completes the family.
--gog-select-options-padding / --gog-select-option-radiusThe gutter around the option list and the row’s own corner, matching what gog-autocomplete and gog-multiselect already had. This panel had no interior at all before 21.12.0, which is why its first and last rows were square inside a rounded corner. The row radius derives from the panel radius less the gutter, so it stays concentric once --gog-density moves the padding.
--gog-select-min-widthThe floor an auto-width trigger cannot collapse past (120px).
--gog-select-chevron-color / -chevron-insetDropdown arrow color and inset. Since 21.3.0 the inset lands on --gog-control-icon-offset, the same line as gog-inputfield’s icons — the three controls now line up in a form.
--gog-select-option-hover-bg / -option-press-bg / -option-selected-colorOption row states.
--gog-select-float-label-reserve / -in-top / -on-bg / -over-gap / -over-reserveFloat-label geometry, derived from the shared --gog-field-float-label-* scale.