Combobox - Skeleton

Label

<script lang="ts">
  import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-svelte';

  const data = [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Orange', value: 'orange' },
    { label: 'Carrot', value: 'carrot' },
    { label: 'Broccoli', value: 'broccoli' },
    { label: 'Spinach', value: 'spinach' },
  ];

  let items = $state(data);

  const collection = $derived(
    useListCollection({
      items: items,
      itemToString: (item) => item.label,
      itemToValue: (item) => item.value,
    }),
  );

  const onOpenChange = () => {
    items = data;
  };

  const onInputValueChange: ComboboxRootProps['onInputValueChange'] = (event) => {
    const filtered = data.filter((item) => item.value.toLowerCase().includes(event.inputValue.toLowerCase()));
    if (filtered.length > 0) {
      items = filtered;
    } else {
      items = data;
    }
  };
</script>

<Combobox class="w-full max-w-md" placeholder="Search..." {collection} {onOpenChange} {onInputValueChange}>
  <Combobox.Label>Label</Combobox.Label>
  <Combobox.Control>
    <Combobox.Input />
    <Combobox.Trigger />
  </Combobox.Control>
  <Portal>
    <Combobox.Positioner class="z-[1]!">
      <Combobox.Content>
        {#each items as item (item.value)}
          <Combobox.Item {item}>
            <Combobox.ItemText>{item.label}</Combobox.ItemText>
            <Combobox.ItemIndicator />
          </Combobox.Item>
        {/each}
      </Combobox.Content>
    </Combobox.Positioner>
  </Portal>
</Combobox>

Groups

Create labelled groups for your items.

<script lang="ts">
  import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-svelte';

  const data = [
    { label: 'Apple', value: 'apple', type: 'Fruits' },
    { label: 'Banana', value: 'banana', type: 'Fruits' },
    { label: 'Orange', value: 'orange', type: 'Fruits' },
    { label: 'Carrot', value: 'carrot', type: 'Vegetables' },
    { label: 'Broccoli', value: 'broccoli', type: 'Vegetables' },
    { label: 'Spinach', value: 'spinach', type: 'Vegetables' },
  ];

  let items = $state(data);

  const collection = $derived(
    useListCollection({
      items: items,
      itemToString: (item) => item.label,
      itemToValue: (item) => item.value,
      groupBy: (item) => item.type,
    }),
  );

  const onOpenChange = () => {
    items = data;
  };

  const onInputValueChange: ComboboxRootProps['onInputValueChange'] = (event) => {
    const filtered = data.filter((item) => item.value.toLowerCase().includes(event.inputValue.toLowerCase()));
    if (filtered.length > 0) {
      items = filtered;
    } else {
      items = data;
    }
  };
</script>

<Combobox class="w-full max-w-md" placeholder="Search..." {collection} {onOpenChange} {onInputValueChange}>
  <Combobox.Control>
    <Combobox.Input />
    <Combobox.Trigger />
  </Combobox.Control>
  <Portal>
    <Combobox.Positioner class="z-[1]!">
      <Combobox.Content>
        {#each collection.group() as [type, items] (type)}
          <Combobox.ItemGroup>
            <Combobox.ItemGroupLabel>{type}</Combobox.ItemGroupLabel>
            {#each items as item (item.value)}
              <Combobox.Item {item}>
                <Combobox.ItemText>{item.label}</Combobox.ItemText>
                <Combobox.ItemIndicator />
              </Combobox.Item>
            {/each}
          </Combobox.ItemGroup>
        {/each}
      </Combobox.Content>
    </Combobox.Positioner>
  </Portal>
</Combobox>

Auto Highlight

Search for any option, then tap Enter on your keyboard to automatically select it.

<script lang="ts">
  import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-svelte';

  const data = [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Orange', value: 'orange' },
    { label: 'Carrot', value: 'carrot' },
    { label: 'Broccoli', value: 'broccoli' },
    { label: 'Spinach', value: 'spinach' },
  ];

  let items = $state(data);

  const collection = $derived(
    useListCollection({
      items: items,
      itemToString: (item) => item.label,
      itemToValue: (item) => item.value,
    }),
  );

  const onOpenChange = () => {
    items = data;
  };

  const onInputValueChange: ComboboxRootProps['onInputValueChange'] = (event) => {
    const filtered = data.filter((item) => item.value.toLowerCase().includes(event.inputValue.toLowerCase()));
    if (filtered.length > 0) {
      items = filtered;
    } else {
      items = data;
    }
  };
</script>

<Combobox class="w-full max-w-md" placeholder="Search..." {collection} {onOpenChange} {onInputValueChange} inputBehavior="autohighlight">
  <Combobox.Control>
    <Combobox.Input />
    <Combobox.Trigger />
  </Combobox.Control>
  <Portal>
    <Combobox.Positioner class="z-[1]!">
      <Combobox.Content>
        {#each items as item (item.value)}
          <Combobox.Item {item}>
            <Combobox.ItemText>{item.label}</Combobox.ItemText>
            <Combobox.ItemIndicator />
          </Combobox.Item>
        {/each}
      </Combobox.Content>
    </Combobox.Positioner>
  </Portal>
</Combobox>

Multiple

To maintain filtering functionality and improve clarity for users, we recommend displaying each selected value outside the perimeter of the Combobox component.

<script lang="ts">
  import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-svelte';

  const data = [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Orange', value: 'orange' },
    { label: 'Carrot', value: 'carrot' },
    { label: 'Broccoli', value: 'broccoli' },
    { label: 'Spinach', value: 'spinach' },
  ];

  let value: string[] = $state([]);
  let items = $state(data);

  const collection = $derived(
    useListCollection({
      items: items,
      itemToString: (item) => item.label,
      itemToValue: (item) => item.value,
    }),
  );

  const onOpenChange = () => {
    items = data;
  };

  const onInputValueChange: ComboboxRootProps['onInputValueChange'] = (event) => {
    const filtered = data.filter((item) => item.value.toLowerCase().includes(event.inputValue.toLowerCase()));
    if (filtered.length > 0) {
      items = filtered;
    } else {
      items = data;
    }
  };

  const onValueChange: ComboboxRootProps['onValueChange'] = (event) => {
    value = event.value;
  };
</script>

<div class="grid gap-2 w-full max-w-md">
  <Combobox placeholder="Search..." {collection} {onOpenChange} {onInputValueChange} {value} {onValueChange} multiple>
    <Combobox.Control>
      <Combobox.Input />
      <Combobox.Trigger />
    </Combobox.Control>
    <Portal>
      <Combobox.Positioner class="z-[1]!">
        <Combobox.Content>
          {#each items as item (item.value)}
            <Combobox.Item {item}>
              <Combobox.ItemText>{item.label}</Combobox.ItemText>
              <Combobox.ItemIndicator />
            </Combobox.Item>
          {/each}
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox>
  <div class="flex flex-wrap gap-2">
    {#each value as item (item)}
      <span class="badge preset-filled">
        {item}
      </span>
    {/each}
  </div>
</div>

Disabled Item

<script lang="ts">
  import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-svelte';

  const data = [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Orange', value: 'orange' },
    { label: 'Carrot', value: 'carrot' },
    { label: 'Broccoli', value: 'broccoli' },
    { label: 'Spinach', value: 'spinach' },
  ];

  let items = $state(data);

  const collection = $derived(
    useListCollection({
      items: items,
      itemToString: (item) => item.label,
      itemToValue: (item) => item.value,
      isItemDisabled: (item) => item.value === 'banana',
    }),
  );

  const onOpenChange = () => {
    items = data;
  };

  const onInputValueChange: ComboboxRootProps['onInputValueChange'] = (event) => {
    const filtered = data.filter((item) => item.value.toLowerCase().includes(event.inputValue.toLowerCase()));
    if (filtered.length > 0) {
      items = filtered;
    } else {
      items = data;
    }
  };
</script>

<Combobox class="w-full max-w-md" placeholder="Search..." {collection} {onOpenChange} {onInputValueChange}>
  <Combobox.Control>
    <Combobox.Input />
    <Combobox.Trigger />
  </Combobox.Control>
  <Portal>
    <Combobox.Positioner class="z-[1]!">
      <Combobox.Content>
        {#each items as item (item.value)}
          <Combobox.Item {item}>
            <Combobox.ItemText>{item.label}</Combobox.ItemText>
            <Combobox.ItemIndicator />
          </Combobox.Item>
        {/each}
      </Combobox.Content>
    </Combobox.Positioner>
  </Portal>
</Combobox>

Custom Filter

Try mistyping apple or banana to see the custom filter using the fuzzy search from Fuse.js in action.

<script lang="ts">
  import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-svelte';
  import Fuse from 'fuse.js';

  const data = [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Orange', value: 'orange' },
    { label: 'Carrot', value: 'carrot' },
    { label: 'Broccoli', value: 'broccoli' },
    { label: 'Spinach', value: 'spinach' },
  ];

  const fuse = new Fuse(data, {
    keys: ['label', 'value'],
    threshold: 0.3,
  });

  let items = $state(data);

  const collection = $derived(
    useListCollection({
      items: items,
      itemToString: (item) => item.label,
      itemToValue: (item) => item.value,
    }),
  );

  const onOpenChange = () => {
    items = data;
  };

  const onInputValueChange: ComboboxRootProps['onInputValueChange'] = (event) => {
    const results = fuse.search(event.inputValue);
    if (results.length > 0) {
      items = results.map((result) => result.item);
    } else {
      items = data;
    }
  };
</script>

<Combobox class="w-full max-w-md" placeholder="Search..." {collection} {onOpenChange} {onInputValueChange}>
  <Combobox.Control>
    <Combobox.Input />
    <Combobox.Trigger />
  </Combobox.Control>
  <Portal>
    <Combobox.Positioner class="z-[1]!">
      <Combobox.Content>
        {#each items as item (item.value)}
          <Combobox.Item {item}>
            <Combobox.ItemText>{item.label}</Combobox.ItemText>
            <Combobox.ItemIndicator />
          </Combobox.Item>
        {/each}
      </Combobox.Content>
    </Combobox.Positioner>
  </Portal>
</Combobox>

Direction

Label

<script lang="ts">
  import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-svelte';

  const data = [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Orange', value: 'orange' },
    { label: 'Carrot', value: 'carrot' },
    { label: 'Broccoli', value: 'broccoli' },
    { label: 'Spinach', value: 'spinach' },
  ];

  let items = $state(data);

  const collection = $derived(
    useListCollection({
      items: items,
      itemToString: (item) => item.label,
      itemToValue: (item) => item.value,
    }),
  );

  const onOpenChange = () => {
    items = data;
  };

  const onInputValueChange: ComboboxRootProps['onInputValueChange'] = (event) => {
    const filtered = data.filter((item) => item.value.toLowerCase().includes(event.inputValue.toLowerCase()));
    if (filtered.length > 0) {
      items = filtered;
    } else {
      items = data;
    }
  };
</script>

<Combobox class="w-full max-w-md" placeholder="Search..." {collection} {onOpenChange} {onInputValueChange} dir="rtl">
  <Combobox.Label>Label</Combobox.Label>
  <Combobox.Control>
    <Combobox.Input />
    <Combobox.Trigger />
  </Combobox.Control>
  <Portal>
    <Combobox.Positioner class="z-[1]!">
      <Combobox.Content>
        {#each items as item (item.value)}
          <Combobox.Item {item}>
            <Combobox.ItemText>{item.label}</Combobox.ItemText>
            <Combobox.ItemIndicator />
          </Combobox.Item>
        {/each}
      </Combobox.Content>
    </Combobox.Positioner>
  </Portal>
</Combobox>

Guidelines

Z-Index

By default we do not take an opinionated stance regarding z-index stacking. The result is the component can sometimes be occluded beneath other elements with a higher index. The Z-Index can controlled by applying a utility class to the Positioner component part.

<script lang="ts">
  import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-svelte';

  const data = [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Orange', value: 'orange' },
    { label: 'Carrot', value: 'carrot' },
    { label: 'Broccoli', value: 'broccoli' },
    { label: 'Spinach', value: 'spinach' },
  ];

  let items = $state(data);

  const collection = $derived(
    useListCollection({
      items: items,
      itemToString: (item) => item.label,
      itemToValue: (item) => item.value,
    }),
  );

  const onOpenChange = () => {
    items = data;
  };

  const onInputValueChange: ComboboxRootProps['onInputValueChange'] = (event) => {
    const filtered = data.filter((item) => item.value.toLowerCase().includes(event.inputValue.toLowerCase()));
    if (filtered.length > 0) {
      items = filtered;
    } else {
      items = data;
    }
  };
</script>

<Combobox class="w-full max-w-md" placeholder="Search..." {collection} {onOpenChange} {onInputValueChange}>
  <Combobox.Control>
    <Combobox.Input />
    <Combobox.Trigger />
  </Combobox.Control>
  <Portal>
    <Combobox.Positioner class="z-50">
      <Combobox.Content>
        {#each items as item (item.value)}
          <Combobox.Item {item}>
            <Combobox.ItemText>{item.label}</Combobox.ItemText>
            <Combobox.ItemIndicator />
          </Combobox.Item>
        {/each}
      </Combobox.Content>
    </Combobox.Positioner>
  </Portal>
</Combobox>

Max Items

We recommend no more than 500 items max. For normal usage, a few dozen will provide the best performance.

API Reference

Root

Property	Default	Type
`open`	-	boolean \| undefined The controlled open state of the combobox
`defaultOpen`	-	boolean \| undefined The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox.
`ids`	-	Partial<{ root: string; label: string; control: string; input: string; content: string; trigger: string; clearTrigger: string; item: (id: string, index?: number \| undefined) => string; positioner: string; itemGroup: (id: string \| number) => string; itemGroupLabel: (id: string \| number) => string; }> \| undefined The ids of the elements in the combobox. Useful for composition.
`inputValue`	-	string \| undefined The controlled value of the combobox's input
`defaultInputValue`	""	string \| undefined 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.
`name`	-	string \| undefined The `name` attribute of the combobox's input. Useful for form submission
`form`	-	string \| undefined The associate form of the combobox.
`disabled`	-	boolean \| undefined Whether the combobox is disabled
`readOnly`	-	boolean \| undefined Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it
`invalid`	-	boolean \| undefined Whether the combobox is invalid
`required`	-	boolean \| undefined Whether the combobox is required
`placeholder`	-	string \| undefined The placeholder text of the combobox's input
`defaultHighlightedValue`	-	string \| null \| undefined The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox.
`highlightedValue`	-	string \| null \| undefined The controlled highlighted value of the combobox
`value`	-	string[] \| undefined The controlled value of the combobox's selected items
`defaultValue`	[]	string[] \| undefined 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.
`inputBehavior`	"none"	"autohighlight" \| "autocomplete" \| "none" \| undefined 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
`selectionBehavior`	"replace"	"clear" \| "replace" \| "preserve" \| undefined 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
`autoFocus`	-	boolean \| undefined Whether to autofocus the input on mount
`openOnClick`	false	boolean \| undefined Whether to open the combobox popup on initial click on the input
`openOnChange`	true	boolean \| ((details: InputValueChangeDetails) => boolean) \| undefined Whether to show the combobox when the input value changes
`allowCustomValue`	-	boolean \| undefined Whether to allow typing custom values in the input
`alwaysSubmitOnEnter`	false	boolean \| undefined Whether to always submit on Enter key press, even if popup is open. Useful for single-field autocomplete forms where Enter should submit the form.
`loopFocus`	true	boolean \| undefined Whether to loop the keyboard navigation through the items
`positioning`	{ placement: "bottom-start" }	PositioningOptions \| undefined The positioning options to dynamically position the menu
`onInputValueChange`	-	((details: InputValueChangeDetails) => void) \| undefined Function called when the input's value changes
`onValueChange`	-	((details: ValueChangeDetails<any>) => void) \| undefined Function called when a new item is selected
`onHighlightChange`	-	((details: HighlightChangeDetails<any>) => void) \| undefined Function called when an item is highlighted using the pointer or keyboard navigation.
`onSelect`	-	((details: SelectionDetails) => void) \| undefined Function called when an item is selected
`onOpenChange`	-	((details: OpenChangeDetails) => void) \| undefined Function called when the popup is opened
`translations`	-	IntlTranslations \| undefined Specifies the localized strings that identifies the accessibility elements and their states
`collection`	-	ListCollection<any> \| undefined The collection of items
`multiple`	-	boolean \| undefined 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.
`closeOnSelect`	-	boolean \| undefined Whether to close the combobox when an item is selected.
`openOnKeyPress`	true	boolean \| undefined Whether to open the combobox on arrow key press
`scrollToIndexFn`	-	((details: ScrollToIndexDetails) => void) \| undefined Function to scroll to a specific index
`composite`	true	boolean \| undefined Whether the combobox is a composed with other composite widgets like tabs
`disableLayer`	-	boolean \| undefined Whether to disable registering this a dismissable layer
`navigate`	-	((details: NavigateDetails) => void) \| null \| undefined Function to navigate to the selected item
`dir`	"ltr"	"ltr" \| "rtl" \| undefined The document's text/writing direction.
`getRootNode`	-	(() => ShadowRoot \| Node \| Document) \| undefined A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.
`onPointerDownOutside`	-	((event: PointerDownOutsideEvent) => void) \| undefined Function called when the pointer is pressed down outside the component
`onFocusOutside`	-	((event: FocusOutsideEvent) => void) \| undefined Function called when the focus is moved outside the component
`onInteractOutside`	-	((event: InteractOutsideEvent) => void) \| undefined Function called when an interaction happens outside the component
`element`	-	Snippet<[HTMLAttributes<"div">]> \| undefined Render the element yourself

RootProvider

Property	Default	Type
`value`	-	() => ComboboxApi<PropTypes, any>
`element`	-	Snippet<[HTMLAttributes<"div">]> \| undefined Render the element yourself

RootContext

Property	Default	Type
`children`	-	Snippet<[() => ComboboxApi<PropTypes, any>]>

Label

Property	Default	Type
`element`	-	Snippet<[HTMLAttributes<"label">]> \| undefined Render the element yourself

Control

Property	Default	Type
`element`	-	Snippet<[HTMLAttributes<"div">]> \| undefined Render the element yourself

Input

Property	Default	Type
`element`	-	Snippet<[HTMLAttributes<"input">]> \| undefined Render the element yourself

Trigger

Property	Default	Type
`element`	-	Snippet<[HTMLAttributes<"button">]> \| undefined Render the element yourself

Positioner

Property	Default	Type
`element`	-	Snippet<[HTMLAttributes<"div">]> \| undefined Render the element yourself

Content

Property	Default	Type
`element`	-	Snippet<[HTMLAttributes<"ul">]> \| undefined Render the element yourself

ItemGroup

Property	Default	Type
`element`	-	Snippet<[HTMLAttributes<"div">]> \| undefined Render the element yourself

ItemGroupLabel

Property	Default	Type
`element`	-	Snippet<[HTMLAttributes<"div">]> \| undefined Render the element yourself

Item

Property	Default	Type
`persistFocus`	-	boolean \| undefined Whether hovering outside should clear the highlighted state
`item`	-	any The item to render
`element`	-	Snippet<[HTMLAttributes<"li">]> \| undefined Render the element yourself

ItemText

Property	Default	Type
`element`	-	Snippet<[HTMLAttributes<"span">]> \| undefined Render the element yourself

ItemIndicator

Property	Default	Type
`element`	-	Snippet<[HTMLAttributes<"div">]> \| undefined Render the element yourself