SvComboBox

An editable combobox: type to filter a portalled option list and pick a value. Unlike an autocomplete, the value must come from the list - unmatched text reverts on blur. Filtering is local by default, or hand it a loadOptions for remote search.

SvComboBox is the searchable single-select. It is controlled through value + onChange, groups options by their group heading, and keeps the panel visible outside any scroll container. Pass loadOptions and it turns into a debounced, race-safe server search (local filtering switches off and the returned list is shown as-is), with loading and empty-state text you can localize via messages.

Related: SvDropDownList · SvAutoComplete · Selection overview

Installation

Add it with the CLI - this drops a ready-to-edit SvComboBox starter into your app:

Prefer to see it first? npx @svgrid/ui try combo-box opens it in a throwaway sandbox - no project needed.

Or install the package and import it directly. SvComboBox ships free in @svgrid/grid (dependency-free):

import { SvComboBox } from '@svgrid/grid'

Example

<script lang="ts">
  import { SvComboBox, type ListOption } from '@svgrid/grid'
  const options: ListOption[] = [
    { value: 'us', label: 'United States' },
    { value: 'gb', label: 'United Kingdom' },
    { value: 'de', label: 'Germany' },
  ]
  let value = $state<string | null>(null)
</script>

<SvComboBox label="Country" {options} {value} onChange={(v) => (value = v)} required />

Props

Options use the shared ListOption shape. ComboMessages is { noResults: string; loading: string; typeMore: string }.

Examples

Remote (server) search

Give loadOptions an async function and SvComboBox debounces the query, keeps only the latest response, and shows a loading state - no local filtering:

<SvComboBox label="User" minLength={2}
  loadOptions={async (q) => (await fetch(`/api/users?q=${q}`)).json()}
  onChange={(v) => (userId = v)} />

Localized strings

Override the empty-state and loading text through messages:

<SvComboBox {options}
  messages={{ noResults: 'Keine Treffer', loading: 'Laden…', typeMore: 'Tippen zum Suchen' }} />

Grouped options

Set a group on options and the filtered panel keeps its section headings.

Dependent remote search

Close loadOptions over another field so the query is scoped by an earlier pick - here cities are searched within the chosen country:

<script lang="ts">
  import { SvComboBox, type ListOption } from '@svgrid/grid'
  let countryId = $state<string | null>(null)
  let cityId = $state<string | number | null>(null)
  const loadCities = async (q: string): Promise<ListOption[]> =>
    (await fetch(`/api/cities?country=${countryId}&q=${q}`)).json()
</script>

<SvComboBox label="City" minLength={2} disabled={!countryId}
  loadOptions={loadCities} value={cityId} onChange={(v) => (cityId = v)} />

Because loadOptions re-reads countryId on each call, switching the country just scopes the next search - and the combobox keeps only the latest response, so an in-flight request for the old country can never win.

Resizable panel

Set resizable and the open panel grows a bottom drag grip ("····"); drag it to grow or shrink the list, and the chosen height sticks for the session. The grip hides automatically when the panel flips upward (there is no room to grow below). The same prop works on SvDropDownList and SvAutoComplete.

<SvComboBox resizable {options} label="Timezone" />

Accessibility

• The input carries role="combobox" with aria-expanded / aria-controls; the panel is a role="listbox" with a roving active option.
• Type to filter, ArrowUp / ArrowDown to move, Enter to pick, Escape to dismiss; unmatched text reverts on blur so the value stays valid.
• label, hint, and error are wired via aria-describedby; pass ariaLabel when there is no visible label.

More examples

Combobox - headless

createCombobox drives the styled SvComboBox and a custom filter-input render, both bound to one value with a readout.

Remote combo box

SvComboBox with a remote dataSource: debounced server search (loadOptions), a loading state, latest-response-wins race handling and a type-to-search hint. Local filtering off.

Sizes

Every control takes the same three sizes, so a dense toolbar and a roomy form can share components.

<script lang="ts">
  import { SvComboBox } from '@svgrid/grid'

  let cityId = $state('')
</script>

<SvComboBox value={cityId} size="sm" />
<SvComboBox value={cityId} size="md" />
<SvComboBox value={cityId} size="lg" />

In a form

The shared field props behave the same on every editor: label names it, hint explains it, and error plus invalid mark it - which is why a validated form does not need per-component handling.

<script lang="ts">
  import { SvComboBox } from '@svgrid/grid'

  let cityId = $state('')
</script>

<SvComboBox
  value={cityId}
  label="Label"
  hint="A short hint"
  required
/>

<SvComboBox
  value={cityId}
  label="Label"
  error="Something is wrong"
  invalid
/>

See also

• Selection overview - the whole picker family at a glance.
• SvDropDownList - pick from a list without typing.
• SvAutoComplete - free text with suggestions (any value allowed).