Combobox

Autocomplete input and command palette with a list of suggestions. Anchored below the trigger (at least as wide as it) on pointer / wide screens; a bottom sheet on compact touch screens.

Usage

const FRAMEWORKS: SparkSelectOption[] = [
  new SparkSelectOption('next.js', 'Next.js'),
  new SparkSelectOption('sveltekit', 'SvelteKit'),
  ...
];

SCombobox({
  value: this.framework!!,
  options: FRAMEWORKS,
  placeholder: 'Select framework…',
  searchPlaceholder: 'Search framework…',
  emptyText: 'No framework found.'
})

Approximate web preview — the HarmonyOS rendering is the reference.

Long lists

Results are virtualized: options that do not match the query are never built, and of the matches only the rows in view are. Try "north 7" or "brk".

// 1 000 options: filtering keeps only the matches, and only the visible
// matches are built (List + Repeat.virtualScroll()). ↑ / ↓ + Enter work from the search field.
SCombobox({
  value: this.place!!,
  options: MANY_PLACES,
  placeholder: 'Select place…',
  searchPlaceholder: 'Search 1 000 places…',
  triggerWidth: 260
})

Approximate web preview — the HarmonyOS rendering is the reference.

MANY_PLACES.length options · place = …

API

Extracted from the @Param / @Event / @BuilderParam declarations in the library sources.

SCombobox

shadcn-vue Combobox (Popover + Command): an outline button showing the selected label and a chevrons-up-down icon; opens a searchable list with a check mark on the selected option.

Anchored below the trigger (as wide as the trigger, at least 200vp) on pointer / wide screens; a bottom sheet on compact touch screens. Selecting the current option again clears it (shadcn behaviour) unless deselectable: false.

The results are virtualized (ADR D14: List + Repeat.virtualScroll()): filtering recomputes the matching rows (O(n) per keystroke, cmdk scoring) and only the visible ones are built — options that do not match are never built at all. ↑ / ↓ move the highlight (the list follows it), Enter picks it.

Panel tokens (ADR D13/D14): --combobox-* (background border-color radius border-width paddingshadow highlight-background highlight-foreground max-height), falling back to the shared --popover-* surface; per instance via tokens.

Prop	Type	Default	Description
value!!	string | undefined	undefined
defaultValue	string	''
options	SparkSelectOption[]	[]
placeholder	ResourceStr	$r('app.string.spark_select_option')
searchPlaceholder	ResourceStr	$r('app.string.spark_search_placeholder')
emptyText	ResourceStr	$r('app.string.spark_no_results')
triggerWidth	Length	200	trigger width (shadcn demo: w-[200px]); '100%' to fill the parent
disabled	boolean	false
deselectable	boolean	true
adaptive	SparkAdaptive SparkAdaptive = 'auto' | 'pointer' | 'touch'	'auto'
tokens	SparkOptionPanelTokens	{}

Event	Type	Default	Description
onValueChange	(v: string) => void	() => { }