Combobox

Enables users to pick from a list of options displayed in a dropdown.

	<script lang="ts">
  import { Combobox } from "bits-ui";
  import { CaretUpDown, Check, OrangeSlice } from "$icons/index.js";
  import { flyAndScale } from "$lib/utils/index.js";
 
  const fruits = [
    { value: "mango", label: "Mango" },
    { value: "watermelon", label: "Watermelon" },
    { value: "apple", label: "Apple" },
    { value: "pineapple", label: "Pineapple" },
    { value: "orange", label: "Orange" }
  ];
 
  let inputValue = "";
  let touchedInput = false;
 
  $: filteredFruits =
    inputValue && touchedInput
      ? fruits.filter((fruit) => fruit.value.includes(inputValue.toLowerCase()))
      : fruits;
</script>
 
<Combobox.Root items={filteredFruits} bind:inputValue bind:touchedInput>
  <div class="relative">
    <OrangeSlice
      class="absolute start-3 top-1/2 size-6 -translate-y-1/2 text-muted-foreground"
    />
    <Combobox.Input
      class="inline-flex h-input w-[296px] truncate rounded-9px border border-border-input bg-background px-11 text-sm transition-colors placeholder:text-foreground-alt/50 focus:outline-none focus:ring-2 focus:ring-foreground focus:ring-offset-2 focus:ring-offset-background"
      placeholder="Search a fruit"
      aria-label="Search a fruit"
    />
    <CaretUpDown
      class="absolute end-3 top-1/2 size-6 -translate-y-1/2 text-muted-foreground"
    />
  </div>
 
  <Combobox.Content
    class="w-full rounded-xl border border-muted bg-background px-1 py-3 shadow-popover outline-none"
    transition={flyAndScale}
    sideOffset={8}
  >
    {#each filteredFruits as fruit (fruit.value)}
      <Combobox.Item
        class="flex h-10 w-full select-none items-center rounded-button py-3 pl-5 pr-1.5 text-sm capitalize outline-none transition-all duration-75 data-[highlighted]:bg-muted"
        value={fruit.value}
        label={fruit.label}
      >
        {fruit.label}
        <Combobox.ItemIndicator class="ml-auto" asChild={false}>
          <Check />
        </Combobox.ItemIndicator>
      </Combobox.Item>
    {:else}
      <span class="block px-5 py-2 text-sm text-muted-foreground">
        No results found
      </span>
    {/each}
  </Combobox.Content>
  <Combobox.HiddenInput name="favoriteFruit" />
</Combobox.Root>

Structure

	<script lang="ts">
	import { Combobox } from "bits-ui";
</script>
 
<Combobox.Root>
	<Combobox.Input />
	<Combobox.Label />
 
	<Combobox.Content>
		<Combobox.Item>
			<Combobox.ItemIndicator />
		</Combobox.Item>
		<Combobox.Separator />
	</Combobox.Content>
	<Combobox.Arrow />
	<Combobox.HiddenInput />
</Combobox.Root>

API Reference

Combobox.Root

The root combobox component which manages & scopes the state of the combobox.

Property	Type	Description
`disabled`	`boolean`	Whether or not the combobox component is disabled. `Default: false`
`multiple`	`boolean`	Whether or not the combobox menu allows multiple selections. `Default: false`
`preventScroll`	`boolean`	Whether or not to prevent scrolling the body when the menu is open. `Default: true`
`closeOnEscape`	`boolean`	Whether to close the combobox menu when the escape key is pressed. `Default: true`
`closeOnOutsideClick`	`boolean`	Whether to close the combobox menu when a click occurs outside of it. `Default: true`
`loop`	`boolean`	Whether or not to loop through the menu items when navigating with the keyboard. `Default: false`
`open`	`boolean`	The open state of the combobox menu. `Default: false`
`onOpenChange`	`function`	A callback that is fired when the combobox menu's open state changes. `Default: —— undefined`
`selected`	`object`	The value of the currently selected item. `Default: —— undefined`
`onSelectedChange`	`function`	A callback that is fired when the combobox menu's value changes. `Default: —— undefined`
`portal`	`union`	Where to render the combobox menu when it is open. Defaults to the body. Can be disabled by passing `null` `Default: —— undefined`
`highlightOnHover`	`boolean`	Whether or not to highlight the currently hovered item. `Default: true`
`name`	`string`	The name to apply to the hidden input element for form submission. `Default: —— undefined`
`required`	`boolean`	Whether or not the combobox menu is required. `Default: false`
`scrollAlignment`	`enum`	The alignment of the highlighted item when scrolling. `Default: 'nearest'`
`inputValue`	`string`	The value of the combobox input element. `Default: —— undefined`
`items`	`Selected[]`	An array of items to add type-safety to the `onSelectedChange` callback. `Default: —— undefined`
`onOutsideClick`	`function`	A callback function called when a click occurs outside of the element. If `event.preventDefault()` is called, the default behavior of closing the element will be prevented. `Default: —— undefined`
`touchedInput`	`boolean`	The touched state of the input. When the menu closes, the state is reset to `false`. Whenever a key is pressed into the input, the state is set to `true`. You can bind to this to handle filtering the items only when the input has been touched. `Default: false`

Slot Property	Type	Description
`ids`	`object`	The ids of the elements within the component, useful when you don't necessarily want to provide a custom ID, but still want access to the ID being assigned (if any).

Combobox.Content

The element which contains the combobox's items.

Property	Type	Description
`transition`	`function`	A Svelte transition function to use when transitioning the content in and out. `Default: —— undefined`
`transitionConfig`	`TransitionConfig`	The configuration to apply to the transition. `Default: —— undefined`
`inTransition`	`function`	A Svelte transition function to use when transitioning the content in and out. `Default: —— undefined`
`inTransitionConfig`	`TransitionConfig`	The configuration to apply to the transition. `Default: —— undefined`
`outTransition`	`function`	A Svelte transition function to use when transitioning the content in and out. `Default: —— undefined`
`outTransitionConfig`	`TransitionConfig`	The configuration to apply to the transition. `Default: —— undefined`
`side`	`enum`	The preferred side of the anchor to render against when open. Will be reversed when collisions occur. Floating UI reference. `Default: —— undefined`
`sideOffset`	`number`	The amount of offset to apply to the menu's position on the x-axis. Floating UI reference. `Default: 0`
`align`	`enum`	The preferred alignment of the anchor to render against when open. Floating UI reference. `Default: —— undefined`
`alignOffset`	`number`	An offset in pixels from the 'start' or 'end' alignment options. Floating UI reference. `Default: 0`
`avoidCollisions`	`boolean`	When `true`, overrides the `side` and `align` options to prevent collisions with the boundary edges. Floating UI reference. `Default: true`
`collisionBoundary`	`union`	A boundary element or array of elements to check for collisions against. Floating UI reference. `Default: —— undefined`
`collisionPadding`	`number`	The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision. Floating UI reference. `Default: 0`
`fitViewport`	`boolean`	Whether the floating element should be constrained to the viewport. Floating UI reference. `Default: false`
`sameWidth`	`boolean`	Whether the content should be the same width as the trigger. Floating UI reference. `Default: false`
`strategy`	`enum`	The positioning strategy to use for the floating element. Floating UI reference. `Default: absolute`
`overlap`	`boolean`	Whether the floating element can overlap the reference element. Floating UI reference. `Default: false`
`asChild`	`boolean`	Whether to use render delegation with this component or not. `Default: false`
`el`	`HTMLDivElement`	The underlying DOM element being rendered. You can bind to this to programatically interact with the element. `Default: —— undefined`

Slot Property	Type	Description
`builder`	`object`	The builder attributes and actions to apply to the element if using the `asChild` prop with delegation.

Data Attribute	Value	Description
`data-combobox-content`	`——`	Present on the content element.

Combobox.Item

A combobox item, which must be a child of the Combobox.Content component.

Property	Type	Description
`label`	`string`	The label of the item, which is displayed in the menu. `Default: —— undefined`
`value`	`unknown`	The value of the item. `Default: —— undefined`
`disabled`	`boolean`	Whether or not the combobox item is disabled. This will prevent interaction/selection. `Default: false`
`asChild`	`boolean`	Whether to use render delegation with this component or not. `Default: false`
`el`	`HTMLDivElement`	The underlying DOM element being rendered. You can bind to this to programatically interact with the element. `Default: —— undefined`

Slot Property	Type	Description
`builder`	`object`	The builder attributes and actions to apply to the element if using the `asChild` prop with delegation.

Data Attribute	Value	Description
`data-state`	`enum`	The state of the item.
`data-disabled`	`——`	Present when the item is disabled.
`data-highlighted`	`——`	Present when the item is highlighted, via keyboard navigation or hover.
`data-combobox-item`	`——`	Present on the item element.

Combobox.Input

A representation of the combobox input element, which is typically displayed in the content.

Property	Type	Description
`placeholder`	`string`	A placeholder value to display when no value is selected. `Default: —— undefined`
`asChild`	`boolean`	Whether to use render delegation with this component or not. `Default: false`

Slot Property	Type	Description
`attrs`	`object`	Additional attributes to apply to the element if using the `asChild` prop with delegation.
`label`	`string`	The label of the currently selected item.

Data Attribute	Value	Description
`data-combobox-input`	`——`	Present on the input element.

Combobox.Label

A label for the combobox input element, which is typically displayed in the content.

Property	Type	Description
`asChild`	`boolean`	Whether to use render delegation with this component or not. `Default: false`
`el`	`HTMLLabelElement`	The underlying DOM element being rendered. You can bind to this to programatically interact with the element. `Default: —— undefined`

Slot Property	Type	Description
`builder`	`object`	The builder attributes and actions to apply to the element if using the `asChild` prop with delegation.

Data Attribute	Value	Description
`data-combobox-label`	`——`	Present on the label element.

Combobox.HiddenInput

A hidden input element which is used to store the combobox menu's value, used for form submission. It receives the same value as the Select.Value component and can receive any props that a normal input element can receive.

Property	Type	Description
`asChild`	`boolean`	Whether to use render delegation with this component or not. `Default: false`
`el`	`HTMLInputElement`	The underlying DOM element being rendered. You can bind to this to programatically interact with the element. `Default: —— undefined`

Slot Property	Type	Description
`builder`	`object`	The builder attributes and actions to apply to the element if using the `asChild` prop with delegation.

Combobox.Arrow

An optional arrow element which points to the content when open.

Property	Type	Description
`size`	`number`	The height and width of the arrow in pixels. `Default: 8`
`asChild`	`boolean`	Whether to use render delegation with this component or not. `Default: false`
`el`	`HTMLDivElement`	The underlying DOM element being rendered. You can bind to this to programatically interact with the element. `Default: —— undefined`

Slot Property	Type	Description
`builder`	`object`	The builder attributes and actions to apply to the element if using the `asChild` prop with delegation.

Data Attribute	Value	Description
`data-arrow`	`——`	Present on the arrow element.