Forms

Combobox

Single-select input that filters a fixed option list as the user types, combining free-text search with constrained values.

import { Combobox } from '@lostgradient/cinder/combobox';
formautocomplete
01

Overview

Filterable dropdown that combines a text input with a selectable option list.

Usage

svelte 
<script lang="ts">
  import Combobox from '@lostgradient/cinder/combobox';
</script>

<Combobox />
Live preview
02

When to use

Use when
  • Choosing one value from a long list where typing is faster than scrolling.
  • Letting users narrow options by substring while still requiring a constrained selection.
Avoid when
  • Picking from a short fixed list with no need to filter — use select instead.
  • Querying remote data or accepting free-text submissions — use search-field instead.
03

Examples

Basic combobox

Type to filter; the list is filtered with a case-insensitive substring match.

Disabled combobox

Disabled combobox cannot be focused or edited.

Typed options with as const

Use `as const` on the options array to infer a precise literal-union type for `T`. TypeScript then rejects any `value` that is not a member of the union (or the empty-string sentinel) at compile time.

04

Props

Props for combobox
Name Type Default Required Bindable Description
id text req Unique identifier — required for label association and ARIA wiring.
value AllowCustom extends true ? string : NoInfer<T>'' '' bind Currently selected value. Bindable. '' when nothing is selected.
onchange (value: AllowCustom extends true ? string : T) => void Called when an option, or an arbitrary value when enabled, is committed.
name string | undefined Native form field name. Renders a hidden input carrying the selected value.
textInputValue text '' bind Free-text input value (the text the user has typed). Bindable.
options readonly ComboboxOption<T>[] req Full set of options to filter. The sole inference source for T.
label text Visible label rendered in a <label> associated via for.
placeholder text Placeholder when no value is selected.
filter (option: ComboboxOption<T>, query: string) => boolean Custom synchronous filter. Receives an option and the current input value; returns true to keep. Defaults to case-insensitive substring match on label.
description text Helper text displayed below the input; wired via aria-describedby.
error text Validation error message; sets aria-invalid="true".
disabled boolean Disables the combobox. Inherited from a wrapping FormField when unset.
required boolean Marks the field required: renders the required marker on the label and sets aria-required on the input. Inherited from a wrapping FormField when unset.
maxVisibleOptions number 200 Hard cap on visible filtered options. Default 200.
customValueAllowed AllowCustom Allow committing typed text that is not present in options.