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';
  const options = [
    { value: 'free', label: 'Free' },
    { value: 'pro', label: 'Pro' },
    { value: 'enterprise', label: 'Enterprise', disabled: true },
  ];
</script>

<Combobox
  id="combobox-disabled"
  label="Plan"
  placeholder="Locked plan selection"
  {options}
  value="pro"
  disabled
/>
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
NameTypeDefaultDescription
id required text Unique identifier — required for label association and ARIA wiring.
value bindable AllowCustom extends true ? string : NoInfer<T>'' '' Currently selected value. Bindable. '' when nothing is selected.
onValueChange (value: AllowCustom extends true ? string : T) => void Called when an option, or an arbitrary value when enabled, is committed.
name text Native form field name. Renders a hidden input carrying the selected value.
textInputValue bindable text '' Free-text input value (the text the user has typed). Bindable.
options required ComboboxOption<T>[] 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.