gog-multiselect
Multiselect
A checkbox-driven multiselect dropdown with optional select-all/clear controls, five sizes, disabled options, placement control, and a body-portaled panel. Once open, Arrow Up/Down move between options, Home/End jump to the first/last, and Escape closes.
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)]:
Angular · 0 valueChange<div>
<gog-multiselect
#frameworksField
label="Frameworks"
placeholder="Pick frameworks"
[options]="frameworks"
[(value)]="picked"
(valueChange)="changes.update((n) => n + 1)"
/>
<!-- selectedNames: the joined labels of the selection, straight off the component. -->
<code>{{ frameworksField.selectedNames() || 'none' }} · {{ changes() }} valueChange</code>
</div>Examples
States
Empty, holding a selection, disabled and with an error. The clear button is there without asking: unlike every other control, clearable defaults to true here, because it shipped a clear button before the input existed — [clearable]="false" drops it. Disabled dims the whole field as one piece
<gog-multiselect label="Value unset" placeholder="Pick frameworks" [options]="frameworks" />
<gog-multiselect label="Two selected" [options]="frameworks" [value]="['angular', 'vue']" />
<gog-multiselect label="Disabled" [options]="frameworks" [value]="['angular', 'vue']" disabled />
<gog-multiselect label="Error" [options]="frameworks" errorMessage="Pick at least one" />A long selection collapses to +N
The trigger shows what fits on one line and a count for the rest; the labels are measured with canvas.measureText rather than by rendering candidates. The count is aria-hidden, and the whole selection is listed in the trigger's tooltip, bound only while something is hidden. Shrink the window to watch it re-measure: the space changes when the container resizes, which Angular never renders for, so a ResizeObserver drives it.
10 selected<!-- Ten selected: what fits stays, the rest collapses to +N, listed in full in the tooltip. -->
<div>
<gog-multiselect label="Countries" [options]="countries" showControls [(value)]="picked" />
<code>{{ picked().length }} selected</code>
</div>Width
A field fills its container by default — the dashed box here. With [fullWidth]="false" the trigger sizes to its own summary, so an empty selection collapses it; minWidth is the floor under that.
<gog-multiselect label="fullWidth (default)" [options]="frameworks" [value]="['angular', 'vue']" />
<!-- Sizes to its own summary, so an empty selection collapses it. -->
<gog-multiselect
label='[fullWidth]="false"'
[fullWidth]="false"
[options]="frameworks"
[value]="['angular', 'vue']"
/>
<gog-multiselect
label='[fullWidth]="false" minWidth="16rem"'
[fullWidth]="false"
minWidth="16rem"
[options]="frameworks"
/>Icon slots, and no visible label
gogDropdownChevron replaces the chevron. The library turns only its own; a custom one gets let-opengogMultiselectClearIcon replaces the glyph in the clear button, not the button, so its name is still clearAriaLabel. ariaLabel names a field with no label.
<!-- The library turns only its own chevron; a custom one draws its state from open. -->
<gog-multiselect label="Chevron slot" [options]="frameworks" [value]="['angular']">
<ng-template gogDropdownChevron let-open>
<gog-icon [name]="open ? 'sort-up' : 'sort'" />
</ng-template>
</gog-multiselect>
<!-- The glyph inside the clear button, not the button: its name is still clearAriaLabel. -->
<gog-multiselect label="Clear-icon slot" [options]="frameworks" [value]="['angular']">
<ng-template gogMultiselectClearIcon>
<gog-icon name="trash" />
</ng-template>
</gog-multiselect>
<gog-multiselect
ariaLabel="Frameworks (no visible label)"
placeholder="Pick frameworks"
[options]="frameworks"
/>Your own objects
optionLabel, optionValue and optionDisabled take a property path — dot-paths included — or a function. [optionValue]="null" makes the value an array of the option objects themselves. A gogDropdownOption template replaces one row; the per-option checkbox stays, as the control's affordance. [gogDropdownOptionTypeOf]
value: u1value: 0 object(s)<!-- Property paths, dot-paths included: a DTO goes in unmapped. -->
<div>
<gog-multiselect
label="Reviewers (by uuid)"
[options]="members"
optionLabel="profile.fullName"
optionValue="uuid"
optionDisabled="suspended"
[(value)]="memberIds"
/>
<code>value: {{ memberIds().join(', ') || 'none' }}</code>
</div>
<!-- A function label and [optionValue]="null": the value holds the option objects. -->
<div>
<gog-multiselect
label="Reviewers (whole objects)"
placeholder="Pick people"
[options]="members"
[optionLabel]="fullName"
[optionValue]="null"
[(value)]="selected"
>
<!-- [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-multiselect>
<code>value: {{ selected().length }} object(s)</code>
</div>A disabled option
optionDisabled defaults to the disabled property, so an option carrying it needs no binding. The row stays in the list, is announced as disabled, and neither the pointer nor "Select all" picks it up.
value: none<!-- optionDisabled reads `disabled` by default; "Select all" never picks a disabled row. -->
<div>
<gog-multiselect label="Plans" [options]="plans" showControls [(value)]="picked" />
<code>value: {{ picked().join(', ') || 'none' }}</code>
</div>Filtering
filter puts a search box in the panel — worth it past about seven options. The default matcher is a case-insensitive substring of the 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-multiselect-panel-radius and it reshapes to match.
<gog-multiselect label="filter" placeholder="Pick countries" [options]="countries" filter />
<gog-multiselect
label='filterPosition="bottom"'
placeholder="Pick countries"
[options]="countries"
filter
filterPosition="bottom"
filterPlaceholder="Type to search…"
filterEmptyMessage="Nothing matches that"
/>"Select all" and "Clear"
showControls adds the row; controlsPosition puts it above or below the list, and it is sticky there, so it stays reachable in a long list. "Select all" acts on the options currently visible — type 1 into the filter and it selects the eleven that match, not all twenty. Disabled options are never picked up.
<!-- "Select all" acts on the visible options: type "1" and it selects the matches only. -->
<gog-multiselect label="Controls on top" [options]="countries" showControls filter />
<gog-multiselect
label="Controls at the bottom"
[options]="countries"
showControls
controlsPosition="bottom"
filter
/>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.
<!-- 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-multiselect label="Inline panel (clipped)" [options]="countries" dropdownDirection="down" />
</div>
<div style="overflow: hidden; padding: 12px; border: 1px dashed var(--gog-border-color)">
<gog-multiselect
label="appendToBody (escapes)"
[options]="countries"
dropdownDirection="down"
appendToBody
/>
</div>
<div>
<gog-multiselect
label="Panel 240px wide, 160px tall"
[options]="countries"
appendToBody
dropdownWidth="240px"
dropdownMaxHeight="160px"
/>
</div>Virtualized options — virtualize
Both fields hold 10 000 options: the windowed one keeps about twenty rows in the DOM, the eager one builds all 10 000 to show six. Off by default and never switched on at a row count — Ctrl+F finds only rendered rows, :last-child matches the last rendered one. aria-setsize keeps the real count. "Select all" means the whole filtered list, not the rendered window, so it selects all 10 000. Set it app-wide with GOG_CONFIG.dropdown.virtualize.
<!-- "Select all" takes the visible options — the whole filtered list, not the rendered window. -->
<gog-multiselect
label="virtualize"
placeholder="Pick cities"
[options]="cities"
virtualize
filter
showControls
/>
<gog-multiselect label="Eager (default)" placeholder="Pick cities" [options]="cities" filter />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 selection. floatLabelShowPlaceholder brings the placeholder back under the floated label.
@for (variant of variants; track variant) {
<gog-multiselect
[floatLabel]="variant"
[label]="'floatLabel: ' + variant"
placeholder="e.g. Angular"
[options]="frameworks"
/>
<gog-multiselect
[floatLabel]="variant"
[label]="'floatLabel: ' + variant"
[options]="frameworks"
[value]="['angular', 'vue']"
/>
}
<!-- The placeholder shows under the floated label once it has somewhere to float to. -->
<gog-multiselect
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. Validators.required treats the empty array as missing, which makes "at least one" the default meaning of a required multiselect. The trigger carries aria-invalid and points aria-describedby at the message
value: [] · touched: false · disabled: false <div>
<!-- Validators.required treats the empty array as missing: "at least one". -->
<gog-multiselect
label="Frameworks (reactive form)"
placeholder="Pick frameworks"
[options]="frameworks"
[formControl]="control"
errorMessage="Pick at least one"
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.join(', ') }}] · touched: {{ control.touched }} · disabled:
{{ control.disabled }}
</code>
</div>App-wide defaults — GOG_CONFIG
control.size, the dropdown keys and the two control labels set the defaults for every field under the provider; an instance's own input still wins. Open the third field: the filter is at the bottom and the controls read "All of them" / "None". In an app the provider goes in app.config.ts — see Global Configuration.
<gog-multiselect label="Size from the config (lg)" [options]="frameworks" />
<gog-multiselect label='size="sm" — the instance wins' size="sm" [options]="frameworks" />
<!-- dropdown.filter and the two labels: open it. -->
<gog-multiselect label="Filter and labels from the config" [options]="frameworks" showControls />Accessibility
The trigger is a role="combobox" that owns a multi-select role="listbox"; each row is a role="option" carrying aria-selected. Disabled is reported as aria-disabled on the trigger.
- Keyboard — on the trigger, Enter or Space opens the panel and ↓ / ↑ open it on the first or last option. In the list the arrows move and skip disabled options, Home/End jump to the ends, Enter or Space toggles the focused option, Esc closes and returns focus to the trigger, and Tab closes and moves on. The options are one tab stop. Inside a dialog, Escape closes the list first and the dialog on the next press
21.15.0 . - Name —
label, orariaLabel. The+Ncount is hidden from assistive tech; the full selection is in the trigger's description. - Error —
aria-invalidand anaria-describedbypointing at the message.
API Reference
Inputs
| Name | Type | Default | Description |
|---|---|---|---|
selectAllLabel | string | undefined | 'Select all' | Visible text of the panel's select-all button (shown when showControls is on). Also via GOG_CONFIG.labels.selectAll. |
clearAllLabel | string | undefined | 'Clear' | The clear-all button next to it. Also via GOG_CONFIG.labels.clearAll. |
value | (string | number)[] (model) | [] | Two-way bindable selected option ids via [(value)]. 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. |
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) or a function. |
optionValue | string | ((o: TOption) => unknown) | null | 'id' | How an option turns into an emitted value. Set it to null and the control emits the option OBJECTS themselves. |
optionDisabled | string | ((o: TOption) => boolean) | 'disabled' | Which options cannot be picked. |
clearable | boolean | GOG_CONFIG.control.clearable ?? true | Adds a clear button in the outermost trailing position. Deliberately the one control that defaults to true: gog-multiselect shipped a clear button before this input existed, and defaulting it to false would have silently removed it. |
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. "Select all" then takes only the VISIBLE options, so it means what it says while a filter is active. |
filterPosition | 'top' | 'bottom' | GOG_CONFIG.dropdown.filterPosition ?? 'top' | Which end of the panel the search box sticks to — the same vocabulary as controlsPosition, rather than a second one for the same idea. |
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 with your own predicate. |
floatLabel | 'none' | 'in' | 'on' | 'over' | GOG_CONFIG.floatLabel.variant ?? 'none' | Rests the label inside the field like a placeholder and floats it up once the selection is non-empty or the field has focus. |
floatLabelShowPlaceholder | boolean | GOG_CONFIG.floatLabel.showPlaceholder ?? false | Reveals the placeholder once the label has floated out of the way. |
minWidth | string | null | null (--gog-multiselect-min-width, 120px) | Floor for an auto-width trigger, any CSS length — so a short selection cannot collapse the field to its own chrome. |
showControls | boolean | false | Shows a "select all" / "clear" row above (or below) the option list. |
controlsPosition | 'top' | 'bottom' | 'top' | Where the select-all/clear row sits relative to the option list. Sticky either way, so it stays visible while a long list scrolls. |
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 summary instead. |
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. |
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. |
Outputs
| Name | Payload | Description |
|---|---|---|
valueChange | TValue[] | Emitted when the selection changes. Comes from the value model input. |
Content slots
| Directive | Context | Description |
|---|---|---|
gogDropdownOption | $implicit, selected, disabled, label | Replaces one option row. The per-option checkbox stays. |
[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. |
gogMultiselectClearIcon | — | Replaces the glyph inside the clear button; the button and its name stay the component's. |
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.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.clearSelectionGOG_CONFIG.labels.selectAllGOG_CONFIG.labels.clearAll
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 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.
| Token | Description |
|---|---|
--gog-multiselect-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-multiselect-field-bg / -field-border | Field surface and border. |
--gog-multiselect-radius / -min-width | The field’s corner radius — the field only, since 21.12.0 — and the floor an auto-width trigger cannot collapse past. |
--gog-multiselect-focus-border / -focus-ring | Focus state. |
--gog-multiselect-panel-bg / -panel-border / -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-multiselect-panel-gap | Gap between the trigger and the panel. It was --gog-multiselect-panel-offset until 21.13.0, and the old name stopped resolving in 21.14.0. |
--gog-multiselect-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-multiselect-panel-radius | The panel’s own corner, new in 21.12.0 and defaulting to var(--gog-radius). Splitting it off the field’s radius is why shaping the trigger no longer reshapes the overlay; the option row and the filter input both stay concentric with whatever you set here. |
--gog-multiselect-option-hover-bg / -option-press-bg / -option-color | Option row, default, hover and pressed. |
--gog-multiselect-checkbox-border / -checkbox-checked-bg | Per-option selection mark. The mark is a glyph, so -checkbox-bg and -checkbox-checked-color had nothing to paint and were removed in 21.13.0. |
--gog-multiselect-float-label-reserve / -in-top / -on-bg / -over-gap / -over-reserve | Float-label geometry, derived from the shared --gog-field-float-label-* scale. |