Combobox - Skeleton

Label

import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-react';
import { useState } from 'react';

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' },
];

export default function Default() {
  const [items, setItems] = useState(data);

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

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

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

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

Groups

Create labelled groups for your items.

'use client';

import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-react';
import { useState } from 'react';

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' },
];

export default function Group() {
  const [items, setItems] = useState(data);

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

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

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

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

Auto Highlight

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

import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-react';
import { useState } from 'react';

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' },
];

export default function AutoHighlight() {
  const [items, setItems] = useState(data);

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

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

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

  return (
    <Combobox
      className="w-full max-w-md"
      placeholder="Search..."
      collection={collection}
      onOpenChange={onOpenChange}
      onInputValueChange={onInputValueChange}
      inputBehavior="autohighlight"
    >
      <Combobox.Control>
        <Combobox.Input />
        <Combobox.Trigger />
      </Combobox.Control>
      <Portal>
        <Combobox.Positioner className="z-[1]!">
          <Combobox.Content>
            {items.map((item) => (
              <Combobox.Item key={item.value} item={item}>
                <Combobox.ItemText>{item.label}</Combobox.ItemText>
                <Combobox.ItemIndicator />
              </Combobox.Item>
            ))}
          </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.

import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-react';
import { useState } from 'react';

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' },
];

export default function Default() {
  const [value, setValue] = useState<string[]>([]);
  const [items, setItems] = useState(data);

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

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

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

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

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

Disabled Item

import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-react';
import { useState } from 'react';

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' },
];

export default function Default() {
  const [items, setItems] = useState(data);

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

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

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

  return (
    <Combobox
      className="w-full max-w-md"
      placeholder="Search..."
      collection={collection}
      onOpenChange={onOpenChange}
      onInputValueChange={onInputValueChange}
    >
      <Combobox.Control>
        <Combobox.Input />
        <Combobox.Trigger />
      </Combobox.Control>
      <Portal>
        <Combobox.Positioner className="z-[1]!">
          <Combobox.Content>
            {items.map((item) => (
              <Combobox.Item key={item.value} item={item}>
                <Combobox.ItemText>{item.label}</Combobox.ItemText>
                <Combobox.ItemIndicator />
              </Combobox.Item>
            ))}
          </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.

import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-react';
import Fuse from 'fuse.js';
import { useState } from 'react';

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,
});

export default function Default() {
  const [items, setItems] = useState(data);

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

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

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

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

Direction

Label

import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-react';
import { useState } from 'react';

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' },
];

export default function Dir() {
  const [items, setItems] = useState(data);

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

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

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

  return (
    <Combobox
      className="w-full max-w-md"
      placeholder="Search..."
      collection={collection}
      onOpenChange={onOpenChange}
      onInputValueChange={onInputValueChange}
      dir="rtl"
    >
      <Combobox.Label>Label</Combobox.Label>
      <Combobox.Control>
        <Combobox.Input />
        <Combobox.Trigger />
      </Combobox.Control>
      <Portal>
        <Combobox.Positioner className="z-[1]!">
          <Combobox.Content>
            {items.map((item) => (
              <Combobox.Item key={item.value} item={item}>
                <Combobox.ItemText>{item.label}</Combobox.ItemText>
                <Combobox.ItemIndicator />
              </Combobox.Item>
            ))}
          </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.

import { Combobox, Portal, type ComboboxRootProps, useListCollection } from '@skeletonlabs/skeleton-react';
import { useState } from 'react';

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' },
];

export default function ZIndex() {
  const [items, setItems] = useState(data);

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

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

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

  return (
    <Combobox
      className="w-full max-w-md"
      placeholder="Search..."
      collection={collection}
      onOpenChange={onOpenChange}
      onInputValueChange={onInputValueChange}
    >
      <Combobox.Control>
        <Combobox.Input />
        <Combobox.Trigger />
      </Combobox.Control>
      <Portal>
        <Combobox.Positioner className="z-50">
          <Combobox.Content>
            {items.map((item) => (
              <Combobox.Item key={item.value} item={item}>
                <Combobox.ItemText>{item.label}</Combobox.ItemText>
                <Combobox.ItemIndicator />
              </Combobox.Item>
            ))}
          </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`	-	((attributes: HTMLAttributes<"div">) => Element) \| undefined Render the element yourself

RootProvider

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

RootContext

Property	Default	Type
`children`	-	(combobox: ComboboxApi<PropTypes, any>) => ReactNode

Label

Property	Default	Type
`element`	-	((attributes: HTMLAttributes<"label">) => Element) \| undefined Render the element yourself

Control

Property	Default	Type
`element`	-	((attributes: HTMLAttributes<"div">) => Element) \| undefined Render the element yourself

Input

Property	Default	Type
`element`	-	((attributes: HTMLAttributes<"input">) => Element) \| undefined Render the element yourself

Trigger

Property	Default	Type
`element`	-	((attributes: HTMLAttributes<"button">) => Element) \| undefined Render the element yourself

Positioner

Property	Default	Type
`element`	-	((attributes: HTMLAttributes<"div">) => Element) \| undefined Render the element yourself

Content

Property	Default	Type
`element`	-	((attributes: HTMLAttributes<"ul">) => Element) \| undefined Render the element yourself

ItemGroup

Property	Default	Type
`element`	-	((attributes: HTMLAttributes<"div">) => Element) \| undefined Render the element yourself

ItemGroupLabel

Property	Default	Type
`element`	-	((attributes: HTMLAttributes<"div">) => Element) \| 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`	-	((attributes: HTMLAttributes<"li">) => Element) \| undefined Render the element yourself

ItemText

Property	Default	Type
`element`	-	((attributes: HTMLAttributes<"span">) => Element) \| undefined Render the element yourself

ItemIndicator

Property	Default	Type
`element`	-	((attributes: HTMLAttributes<"div">) => Element) \| undefined Render the element yourself