Copy page

Components

ComboSelect

src/lib/components/ui/combo-select/combo-select.svelte

Purpose

A searchable single- or multi-select dropdown. Built on the shadcn-svelte™ Popover and Command primitives (which wrap BITS UI™). Used across the settings area for role, permission, org, and module selection.

Origin

Custom — fully Primebrick-written. Composes shadcn-svelte™ Popover + Command + Badge. Not vendored from any registry.

Usage

Default (single select, object options)

Code
<ComboSelect
  mode="single"
  bind:value
  options={roles}
  valueField="idp_role"
  labelField="label_key"
  isLabelTranslated
  placeholder={$t('settings.selectRole')}
/>

Multi select

Code
<ComboSelect
  mode="multi"
  bind:value={selectedRoles}
  options={roles}
  valueField="idp_role"
  labelField="label_key"
  isLabelTranslated
/>

Disabled options

Code
<ComboSelect
  mode="single"
  bind:value
  options={roles}
  valueField="idp_role"
  labelField="label_key"
  isOptionDisabled={(o) => o.idp_role === 'admin'}
/>

Trigger variants (variant)

The trigger chrome is a closed set, like Button variants:

variant	Chrome
'default' (default)	Primary-gradient border on bg-background — the standard form look
'toolbar'	Neutral InputGroup-style chrome (border-foreground/25, transparent bg) for toolbar strips
'ghost'	The formalized ghost chrome — subtle always-visible border-foreground/25 on transparent bg (same as the toolbar SearchBar). Shared token: inputGhostChromeClasses. For controls embedded inside an already-bordered container (e.g. the color-picker footer)

Code
<ComboSelect mode="single" bind:value options={tokens} variant="ghost" />

Display modes (display)

Options are rendered through the typed display prop — a closed set, like Button variants. Pick a built-in template instead of writing a snippet.

display	Renders
'default' (default)	Plain resolved label
'detailed'	Two-line row — label + secondary value (mono, muted). The secondary line comes from secondaryField; when omitted it shows the resolved value. Covers the common "label + key" layout
'badge'	The option rendered as a colored Badge. The color token (e.g. 'emerald-500') is read from colorField (default 'color')
'custom'	Enables itemSnippet/selectedSnippet for fully bespoke rows

Code
<!-- Badge options (statuses, recommendations, ...) -->
<ComboSelect
  mode="single"
  bind:value
  display="badge"
  colorField="color"
  options={[{ value: 'ok', label: 'OK', color: 'emerald-500' }]}
  valueField="value"
  labelField="label"
/>

<!-- Two-line label + key rows -->
<ComboSelect
  mode="single"
  bind:value
  display="detailed"
  options={i18nKeys}
  valueField="key"
  labelField="key"
/>

Custom item rendering (display="custom")

itemSnippet/selectedSnippet are ignored unless display="custom" — in dev the component logs a console warning when snippets are passed with any other display. Use custom only for layouts no built-in display covers (e.g. model cards, avatar rows, conditional badges).

Code
<ComboSelect
  mode="single"
  bind:value
  display="custom"
  options={roles}
  valueField="idp_role"
  labelField="label_key"
>
  {#snippet itemSnippet({ option, selected, resolvedLabel })}
    <span class="flex items-center gap-2">
      {#if selected}<Check class="size-4" />{/if}
      {resolvedLabel}
    </span>
  {/snippet}
</ComboSelect>

Keyword boosting

Pass getSearchKeywords to let users find an option by fields not present in the value/label (e.g. searching a role by its permissions). Keywords are passed to bits-ui's Command.Item keywords prop for scoring.

Code
<ComboSelect
  mode="single"
  bind:value
  options={roles}
  valueField="idp_role"
  labelField="label_key"
  getSearchKeywords={(o) => o.permissions ?? []}
/>

Props

Full prop table: see API reference — combo-select.

Key props: mode, value (bindable), options, valueField, labelField, isLabelTranslated, searchable, disabled, loading, display, colorField, secondaryField, itemSnippet, selectedSnippet (only with display="custom"), isOptionDisabled, getSearchKeywords.

Next steps

• Component catalog
• UI stack
• API reference