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" />
}gog-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.
Import the component and drop it into a template.
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> 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" />
} 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.
<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"
/> 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 /> 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"
/>gogDropdownChevron replaces the chevron. The library turns only its own; a custom one gets let-openariaLabel 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"
/>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]option.profile.role fails the build.
value: u1value: 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>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>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"
/>'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" />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>virtualizeBoth 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.
'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"
/> 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>GOG_CONFIGcontrol.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" /> 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.
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. aria-invalid on the trigger and an aria-describedby pointing at the message, which is a role="alert". aria-setsize and aria-posinset carry the real list, so a screen reader hears "10 000 items", not "20". | Name | Type | Default | Description |
|---|---|---|---|
value | TValue | null (model) | null | Two-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. |
label | string | '' | Field label. |
ariaLabel | string | '' | Accessible name for the field when there is no visible label. |
inputId | string | '' | id on the trigger button, and target of the label's for attribute. |
placeholder | string | 'Select...' | Text shown while no option is selected. |
options | readonly TOption[] | [] | The list of choices — your own objects. GogDropdownOption ({ id, name, disabled? }) is just the shape the default accessors expect, not a requirement. |
optionLabel | string | ((o: TOption) => string) | 'name' | How an option turns into its visible text: a property path (dot-paths included, "profile.fullName") or a function. |
optionValue | string | ((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. |
optionDisabled | string | ((o: TOption) => boolean) | 'disabled' | Which options cannot be picked. |
clearable | boolean | GOG_CONFIG.control.clearable ?? false | Adds 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. |
clearAriaLabel | string | 'Clear selection' | Accessible name for that clear button. |
filter | boolean | GOG_CONFIG.dropdown.filter ?? false | Puts 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 / filterEmptyMessage | string | 'Search...' / 'No matches' | Wording for the search box and for the empty result. |
filterMatch | ((option: TOption, query: string) => boolean) | null | null | Replaces 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. |
floatLabelShowPlaceholder | boolean | GOG_CONFIG.floatLabel.showPlaceholder ?? false | Reveals the placeholder once the label has floated out of the way. |
errorMessage | string | '' | 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. |
disabled | boolean | false | Disables the trigger and closes the panel if it is open. |
fullWidth | boolean | true | Fills its container by default. Set false to shrink to fit the selected label instead. |
minWidth | string | null | null (--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. |
dropdownZIndex | number | null | null | Explicit stacking order for the panel. Left unset it falls back to the --gog-dropdown-z token. |
dropdownWidth | string | null | null | Fixed 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. |
dropdownMaxHeight | string | null | null | Fixed panel max-height, any CSS length. Applies only with appendToBody. |
appendToBody | boolean | GOG_CONFIG.dropdown.appendToBody ?? false | Portals 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. |
ripple | boolean | undefined | undefined | Press 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. |
virtualize | boolean | undefined | GOG_CONFIG.dropdown.virtualize ?? false | Renders 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. |
| Name | Payload | Description |
|---|---|---|
valueChange | TValue | null | Emitted when the selection changes — a pick, the clear button, or a forms write. Comes from the value model input. |
| Directive | Context | Description |
|---|---|---|
gogDropdownOption | $implicit, selected, disabled, label | Replaces one option row. label is the resolved label, so a custom row can decorate it rather than re-derive it. |
[gogDropdownOptionTypeOf] | readonly TOption[] — an input on gogDropdownOption | Bind 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. |
gogDropdownChevron | $implicit / open | Replaces the trigger chevron. The library turns only its own; a custom one draws its state from open. |
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.sizeGOG_CONFIG.control.errorDisplayGOG_CONFIG.control.clearableGOG_CONFIG.floatLabel.variantGOG_CONFIG.floatLabel.showPlaceholderGOG_CONFIG.dropdown.appendToBodyGOG_CONFIG.dropdown.directionGOG_CONFIG.dropdown.virtualizeGOG_CONFIG.dropdown.filterGOG_CONFIG.dropdown.filterPositionGOG_CONFIG.ripple.enabled — on the panel’s optionsGOG_CONFIG.labels.clearSelectionThis 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.
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.
| Token | Description |
|---|---|
--gog-select-label-color / -label-font-family / -label-font-size / -label-font-weight / -label-letter-spacing / -label-line-height / -label-text-transform | Field label. Each aliases its --gog-field-label-* counterpart. |
--gog-select-field-bg / -field-border | Field surface and border. |
--gog-select-radius | The 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-ring | Focus state. |
--gog-select-panel-bg / -panel-shadow / -panel-max-width | Dropdown panel surface, and the cap on a panel that sizes to its own content rather than to the trigger. |
--gog-select-panel-gap | Gap 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-height | A 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-radius | The 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-radius | The 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-width | The floor an auto-width trigger cannot collapse past (120px). |
--gog-select-chevron-color / -chevron-inset | Dropdown 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-color | Option row states. |
--gog-select-float-label-reserve / -in-top / -on-bg / -over-gap / -over-reserve | Float-label geometry, derived from the shared --gog-field-float-label-* scale. |