Combobox

A component that combines a text input with a dropdown list for selecting or entering values.

Label

Anatomy

Usage

<script>
  import {Combobox} from 'ui-ingredients';
  import {CheckIcon, ChevronDownIcon, XCloseIcon} from '$lib/icons';

  let items = [
    {label: 'Option 1', value: '1'},
    {label: 'Option 2', value: '2'},
    {label: 'Option 3', value: '3'},
    {label: 'Option 4', value: '4'},
    {label: 'Option 5', value: '5'},
  ];

  /** @type {string[]} */
  let value = $state([]);

  let inputValue = $state('');

  let matches = $derived(
    items.filter(function (item) {
      return item.label.toLowerCase().includes(inputValue.toLowerCase());
    }),
  );

  let collection = $derived(
    Combobox.collection({
      items: matches,
    }),
  );
</script>

<Combobox.Root
  {collection}
  {value}
  {inputValue}
  onValueChange={(detail) => {
    value = detail.value;
  }}
  onInputValueChange={(detail) => {
    inputValue = detail.inputValue;
  }}
>
  <Combobox.Label>Label</Combobox.Label>

  <Combobox.Control>
    <Combobox.Input />
    <Combobox.Trigger>
      <ChevronDownIcon />
    </Combobox.Trigger>
    <Combobox.ClearTrigger>
      <XCloseIcon />
    </Combobox.ClearTrigger>
  </Combobox.Control>

  <Combobox.Positioner>
    <Combobox.Content>
      {#each collection.items as item}
        <Combobox.Item {item}>
          <Combobox.ItemText>{item.label}</Combobox.ItemText>
          <Combobox.ItemIndicator>
            <CheckIcon />
          </Combobox.ItemIndicator>
        </Combobox.Item>
      {/each}
    </Combobox.Content>
  </Combobox.Positioner>
</Combobox.Root>

Usage with Field component

<script>
  import {Combobox, Portal} from 'ui-ingredients';
  import {CheckIcon, ChevronDownIcon, XCloseIcon} from '$lib/icons';

  let items = [
    {label: 'Option 1', value: '1'},
    {label: 'Option 2', value: '2'},
    {label: 'Option 3', value: '3'},
    {label: 'Option 4', value: '4'},
    {label: 'Option 5', value: '5'},
  ];

  /** @type {string[]} */
  let value = $state([]);

  let inputValue = $state('');

  let matches = $derived(
    items.filter(function (item) {
      return item.label.toLowerCase().includes(inputValue.toLowerCase());
    }),
  );

  let collection = $derived(
    Combobox.collection({
      items: matches,
    }),
  );
</script>

<Field.Root>
  <Combobox.Root
    {items}
    {value}
    {inputValue}
    onValueChange={(detail) => {
      value = detail.value;
    }}
    onInputValueChange={(detail) => {
      inputValue = detail.inputValue;
    }}
  >
    <Combobox.Label>Label</Combobox.Label>

    <Combobox.Control>
      <Combobox.Input />
      <Combobox.Trigger>
        <ChevronDownIcon />
      </Combobox.Trigger>
      <Combobox.ClearTrigger>
        <XCloseIcon />
      </Combobox.ClearTrigger>
    </Combobox.Control>

    <Combobox.Positioner>
      <Combobox.Content>
        {#each matches as item (item.value)}
          <Combobox.Item {item}>
            <Combobox.ItemText>{item.label}</Combobox.ItemText>
            <Combobox.ItemIndicator>
              <CheckIcon />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        {/each}
      </Combobox.Content>
    </Combobox.Positioner>
  </Combobox.Root>

  <Field.HelperText>This is a helper text</Field.HelperText>
  <Field.ErrorText>This is an error text</Field.ErrorText>
</Field.Root>

API Reference

Root

Prop	Default	Description
`allowCustomValue`		`boolean` Whether to allow typing custom values in the input
`autoFocus`		`boolean` Whether to autofocus the input on mount
`closeOnSelect`		`boolean` Whether to close the combobox when an item is selected.
`collection`		`ListCollection<T>` The collection of items
`composite`	`true`	`boolean` Whether the combobox is a composed with other composite widgets like tabs
`defaultHighlightedValue`		`string` The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox.
`defaultInputValue`	`""`	`string` The initial value of the combobox's input when rendered. Use when you don't need to control the value of the combobox's input.
`defaultOpen`		`boolean` The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox.
`defaultValue`	`[]`	`string[]` The initial value of the combobox's selected items when rendered. Use when you don't need to control the value of the combobox's selected items.
`disabled`		`boolean` Whether the combobox is disabled
`disableLayer`		`boolean` Whether to disable registering this a dismissable layer
`form`		`string` The associate form of the combobox.
`highlightedValue`		`string` The controlled highlighted value of the combobox
`id`		`string` The unique identifier of the machine.
`ids`		`{ root?: string; label?: string; control?: string; input?: string; content?: string; trigger?: string; clearTrigger?: string; item(id: string, index?: number)?: string; positioner?: string; itemGroup(id: string \| number)?: string; itemGroupLabel(id: string \| number)?: string; }` The ids of the elements in the combobox. Useful for composition.
`inputBehavior`	`"none"`	`"autohighlight" \| "autocomplete" \| "none"` Defines the auto-completion behavior of the combobox. - `autohighlight`: The first focused item is highlighted as the user types - `autocomplete`: Navigating the listbox with the arrow keys selects the item and the input is updated
`inputValue`		`string` The controlled value of the combobox's input
`invalid`		`boolean` Whether the combobox is invalid
`keepMounted`		`boolean` Whether to keep the component mounted after exit.
`lazyMount`		`boolean` Whether to enable lazy mounting.
`loopFocus`	`true`	`boolean` Whether to loop the keyboard navigation through the items
`multiple`		`boolean` Whether to allow multiple selection. Good to know: When `multiple` is `true`, the `selectionBehavior` is automatically set to `clear`. It is recommended to render the selected items in a separate container.
`name`		`string` The `name` attribute of the combobox's input. Useful for form submission
`navigate`		`(details: NavigateDetails) => void` Function to navigate to the selected item
`onFocusOutside`		`(event: FocusOutsideEvent) => void` Function called when the focus is moved outside the component
`onHighlightChange`		`(details: HighlightChangeDetails<T>) => void` Function called when an item is highlighted using the pointer or keyboard navigation.
`onInputValueChange`		`(details: InputValueChangeDetails) => void` Function called when the input's value changes
`onInteractOutside`		`(event: InteractOutsideEvent) => void` Function called when an interaction happens outside the component
`onOpenChange`		`(details: OpenChangeDetails) => void` Function called when the popup is opened
`onPointerDownOutside`		`(event: PointerDownOutsideEvent) => void` Function called when the pointer is pressed down outside the component
`onSelect`		`(details: SelectionDetails) => void` Function called when an item is selected
`onValueChange`		`(details: ValueChangeDetails<T>) => void` Function called when a new item is selected
`open`		`boolean` The controlled open state of the combobox
`openOnChange`	`true`	`boolean \| ((details: InputValueChangeDetails) => boolean)` Whether to show the combobox when the input value changes
`openOnClick`	`false`	`boolean` Whether to open the combobox popup on initial click on the input
`openOnKeyPress`	`true`	`boolean` Whether to open the combobox on arrow key press
`placeholder`		`string` The placeholder text of the combobox's input
`positioning`	`{ placement: "bottom-start" }`	`PositioningOptions` The positioning options to dynamically position the menu
`readOnly`		`boolean` Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it
`required`		`boolean` Whether the combobox is required
`scrollToIndexFn`		`(details: ScrollToIndexDetails) => void` Function to scroll to a specific index
`selectionBehavior`	`"replace"`	`"clear" \| "replace" \| "preserve"` The behavior of the combobox input when an item is selected - `replace`: The selected item string is set as the input value - `clear`: The input value is cleared - `preserve`: The input value is preserved
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`value`		`string[]` The controlled value of the combobox's selected items
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-invalid`	Present when invalid
`data-part`	root
`data-readonly`	Present when read-only
`data-scope`	combobox

ClearTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-invalid`	Present when invalid
`data-part`	clear-trigger
`data-scope`	combobox

Content

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-empty`
`data-part`	content
`data-placement`	The placement of the content
`data-scope`	combobox
`data-state`	"open" \| "closed"

Control

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-part`	control
`data-scope`	combobox
`data-state`	"open" \| "closed"

Input

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-invalid`	Present when invalid
`data-part`	input
`data-scope`	combobox
`data-state`	"open" \| "closed"

Item

Prop	Default	Description
`item`		`any` The item data.
`persistFocus`		`boolean` Whether hovering outside should clear the highlighted state.
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-highlighted`	Present when highlighted
`data-part`	item
`data-scope`	combobox
`data-state`	"checked" \| "unchecked"
`data-value`	The value of the item

ItemGroup

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-empty`
`data-part`	item-group
`data-scope`	combobox

ItemGroupLabel

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

ItemIndicator

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	item-indicator
`data-scope`	combobox
`data-state`	"checked" \| "unchecked"

ItemText

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-highlighted`	Present when highlighted
`data-part`	item-text
`data-scope`	combobox
`data-state`	"checked" \| "unchecked"

Label

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-focus`	Present when focused
`data-invalid`	Present when invalid
`data-part`	label
`data-readonly`	Present when read-only
`data-scope`	combobox

List

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-empty`
`data-part`	list
`data-scope`	combobox

Positioner

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Trigger

Prop	Default	Description
`focusable`		`boolean` Whether the trigger is focusable.
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-focusable`
`data-invalid`	Present when invalid
`data-part`	trigger
`data-readonly`	Present when read-only
`data-scope`	combobox
`data-state`	"open" \| "closed"

Accessibility

Keyboard Support

Key	Description
ArrowDown	When the combobox is closed, opens the listbox and highlights to the first option. When the combobox is open, moves focus to the next option.
ArrowUp	When the combobox is closed, opens the listbox and highlights to the last option. When the combobox is open, moves focus to the previous option.
Home	When the combobox is open, moves focus to the first option.
End	When the combobox is open, moves focus to the last option.
Escape	Closes the listbox.
Enter	Selects the highlighted option and closes the combobox.
Esc	Closes the combobox