ComboBox

A combination of a text input and a dropdown listbox. Users can type to filter the options and select from the filtered list. Fully keyboard accessible.

Import

import {
  ComboBox,
  ComboBoxOption,
  defaultContainsFilter,
} from '@proyecto-viviana/solid-spectrum';

Basic with Filtering

Type to filter the list. Press Enter or click to select.

Select a food

Selected: none

<ComboBox
  items={foods}
  getKey={(item) => item.id}
  getTextValue={(item) => item.name}
  selectedKey={selected()}
  onSelectionChange={setSelected}
  defaultFilter={defaultContainsFilter}
  label="Select a food"
  placeholder="Type to filter..."
>
  {(item) => <ComboBoxOption id={item.id}>{item.name}</ComboBoxOption>}
</ComboBox>

Sizes

Three size variants for different contexts.

Small

Medium

Large

<ComboBox items={foods} size="sm" label="Small" placeholder="Filter..." ...>
<ComboBox items={foods} size="md" label="Medium" placeholder="Filter..." ...>
<ComboBox items={foods} size="lg" label="Large" placeholder="Filter..." ...>

With Description & Validation

Helper text and validation error support.

With Description

Choose your favorite food

Invalid

Please select a valid food item

<ComboBox
  label="Required Food"
  isInvalid
  errorMessage="Please select a food item"
  ...
/>

Disabled

A disabled ComboBox cannot be opened or typed in.

Disabled ComboBox

<ComboBox isDisabled defaultSelectedKey="apple" label="Disabled" ...>

Props

Prop	Type	Default	Description
`items`	T[]	—	Array of items to display
`getKey`	(item: T) => string \| number	—	Extracts the unique key from an item
`getTextValue`	(item: T) => string	—	Extracts the display text for filtering
`selectedKey`	string \| number \| null	—	Controlled selected key
`defaultSelectedKey`	string \| number	—	Uncontrolled default selection
`onSelectionChange`	(key: string \| number \| null) => void	—	Called when selection changes
`defaultFilter`	(item: T, inputValue: string) => boolean	—	Filter function for typing (use defaultContainsFilter)
`label`	string	—	Visible label
`placeholder`	string	—	Input placeholder
`size`	'sm' \| 'md' \| 'lg'	`'md'`	Size variant
`isDisabled`	boolean	`false`	Prevents interaction
`isInvalid`	boolean	`false`	Shows error styling
`errorMessage`	string	—	Validation error message
`description`	string	—	Helper text

Accessibility

Uses combobox ARIA role with aria-expanded and aria-haspopup
Arrow keys navigate the list; Enter/Space select; Escape closes
Active option communicated via aria-activedescendant
Supports type-ahead filtering natively via defaultFilter