Combobox

Installation

pnpm dlx shadcn-svelte@latest add https://coss-sv.vercel.app/r/combobox.json

Usage

Single Selection

<script lang="ts">
  import * as Combobox from "$lib/components/ui/combobox/index.js";
</script>

<script lang="ts">
  const items = [
    { value: "apple", label: "Apple" },
    { value: "banana", label: "Banana" },
    { value: "orange", label: "Orange" },
    { value: "grape", label: "Grape" },
  ];
</script>

<Combobox.Root {items}>
  <Combobox.Input placeholder="Select an item..." />
  <Combobox.Popup>
    <Combobox.Empty>No results found.</Combobox.Empty>
    <Combobox.List>
      <Combobox.Collection>
        {#snippet children(item)}
          <Combobox.Item value={item}>{item.label}</Combobox.Item>
        {/snippet}
      </Combobox.Collection>
    </Combobox.List>
  </Combobox.Popup>
</Combobox.Root>

Multiple Selection

<script lang="ts">
  import * as Combobox from "$lib/components/ui/combobox/index.js";
</script>

<script lang="ts">
  const items = [
    { value: "apple", label: "Apple" },
    { value: "banana", label: "Banana" },
    { value: "orange", label: "Orange" },
    { value: "grape", label: "Grape" },
  ] as const;
  type Item = (typeof items)[number];
</script>

<Combobox.Root {items} multiple>
  <Combobox.Chips>
    <Combobox.Value>
      {#snippet children(value: Item[])}
        {#each value as item (item.value)}
          <Combobox.Chip aria-label={item.value} value={item.value}>
            {item.label}
          </Combobox.Chip>
        {/each}
        <Combobox.ChipsInput
          aria-label="Select an item"
          placeholder={value.length > 0 ? undefined : "Select an item..."}
        />
      {/snippet}
    </Combobox.Value>
  </Combobox.Chips>
  <Combobox.Popup>
    <Combobox.Empty>No results found.</Combobox.Empty>
    <Combobox.List>
      <Combobox.Collection>
        {#snippet children(item: Item)}
          <Combobox.Item value={item}>{item.label}</Combobox.Item>
        {/snippet}
      </Combobox.Collection>
    </Combobox.List>
  </Combobox.Popup>
</Combobox.Root>

API Reference

Combobox.Root

The root combobox component. Manages the combobox state and provides context to child components.

Prop	Type	Description
`items`	`readonly unknown[]`	The array of items to display in the combobox
`multiple`	`boolean`	Whether to allow multiple selection
`open`	`boolean`	Controls whether the popup is open
`children`	`Snippet`	Combobox content
`...props`	`ComboboxRootProps`	All Shards UI Combobox props are supported

Combobox.Input

The input field component for single selection mode with extended features for size variants and addon support.

Prop	Type	Default	Description
`size`	`"sm" \\| "default" \\| "lg"`	`"default"`	The size variant of the input field
`startAddon`	`Snippet`	-	Content to display at the start of the input, such as an icon
`showTrigger`	`boolean`	`true`	Whether to display a trigger button on the right side of the input
`showClear`	`boolean`	`false`	Whether to display a clear button on the right side of the input when there is a value
`triggerProps`	`ComboboxTriggerProps`	-	Props forwarded to the internal trigger button, useful for overriding `aria-label`
`clearProps`	`ComboboxClearProps`	-	Props forwarded to the internal clear button, useful for overriding `aria-label`
`class`	`string`	-	Additional CSS classes to apply to the component
`...props`	`ComboboxInputProps`	-	All standard combobox input attributes are supported

The popup container that displays the combobox options.

Prop	Type	Description
`class`	`string`	Additional CSS classes to apply to the component
`portalProps`	`ComboboxPopupProps["portalProps"]`	Props forwarded to the internal portal
`...props`	`ComboboxPopupProps`	All standard combobox popup attributes are supported

Combobox.List

A scrollable container for combobox items.

Prop	Type	Description
`class`	`string`	Additional CSS classes to apply to the component
`children`	`Snippet`	List content
`...props`	`ComboboxListProps`	All standard combobox list attributes are supported

Combobox.Item

An individual selectable combobox item.

Prop	Type	Description
`value`	`unknown`	The value of the item
`class`	`string`	Additional CSS classes to apply to the component
`children`	`Snippet`	Item content
`...props`	`ComboboxItemProps`	All standard combobox item attributes are supported

Combobox.Empty

Displays a message when no results are found.

Prop	Type	Description
`class`	`string`	Additional CSS classes to apply to the component
`children`	`Snippet`	Empty-state content
`...props`	`ComboboxEmptyProps`	All standard combobox empty attributes are supported

Combobox.Group

Groups related combobox items together.

Prop	Type	Description
`items`	`readonly unknown[]`	The array of items in this group
`class`	`string`	Additional CSS classes to apply to the component
`children`	`Snippet`	Group content
`...props`	`ComboboxGroupProps`	All standard combobox group attributes are supported

Combobox.GroupLabel

Displays a label for a combobox group.

Prop	Type	Description
`class`	`string`	Additional CSS classes to apply to the component
`children`	`Snippet`	Label content
`...props`	`ComboboxGroupLabelProps`	All standard combobox group label attributes are supported

Combobox.Collection

Used to wrap items within a group for rendering.

Prop	Type	Description
`children`	`Snippet<[unknown]>`	Renders each filtered item
`...props`	`ComponentProps<typeof Combobox.Collection>`	All standard combobox collection attributes are supported

Combobox.Chips

Container for displaying selected chips in multiple selection mode.

Prop	Type	Description
`startAddon`	`Snippet`	Content to display at the start of the chips area
`class`	`string`	Additional CSS classes to apply to the component
`children`	`Snippet`	Chips content
`...props`	`ComboboxChipsProps`	All standard div attributes are supported

Combobox.ChipsInput

The input field component for use inside Combobox.Chips in multiple selection mode. This is a minimal input without the wrapper, trigger, or clear button.

Prop	Type	Default	Description
`size`	`"sm" \\| "default" \\| "lg"`	`"default"`	The size variant of the input field
`class`	`string`	-	Additional CSS classes to apply to the component
`...props`	`ComboboxChipsInputProps`	-	All standard combobox input attributes are supported

Combobox.Chip

An individual chip representing a selected item in multiple selection mode.

Prop	Type	Description
`removeProps`	`ComboboxChipRemoveProps`	Props forwarded to the internal remove button, useful for overriding `aria-label`
`class`	`string`	Additional CSS classes to apply to the component
`children`	`Snippet`	Chip content
`...props`	`ComboboxChipProps`	All standard combobox chip attributes are supported