Combobox

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

	<script lang="ts">
  import { Combobox } from "bits-ui";
  import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
  import Check from "phosphor-svelte/lib/Check";
  import OrangeSlice from "phosphor-svelte/lib/OrangeSlice";
  import CaretDoubleUp from "phosphor-svelte/lib/CaretDoubleUp";
  import CaretDoubleDown from "phosphor-svelte/lib/CaretDoubleDown";
 
  const fruits = [
    { value: "mango", label: "Mango" },
    { value: "watermelon", label: "Watermelon" },
    { value: "apple", label: "Apple" },
    { value: "pineapple", label: "Pineapple" },
    { value: "orange", label: "Orange" },
    { value: "grape", label: "Grape" },
    { value: "strawberry", label: "Strawberry" },
    { value: "banana", label: "Banana" },
    { value: "kiwi", label: "Kiwi" },
    { value: "peach", label: "Peach" },
    { value: "cherry", label: "Cherry" },
    { value: "blueberry", label: "Blueberry" },
    { value: "raspberry", label: "Raspberry" },
    { value: "blackberry", label: "Blackberry" },
    { value: "plum", label: "Plum" },
    { value: "apricot", label: "Apricot" },
    { value: "pear", label: "Pear" },
    { value: "grapefruit", label: "Grapefruit" }
  ];
 
  let searchValue = $state("");
 
  const filteredFruits = $derived(
    searchValue === ""
      ? fruits
      : fruits.filter((fruit) =>
          fruit.label.toLowerCase().includes(searchValue.toLowerCase())
        )
  );
</script>
 
<Combobox.Root
  type="single"
  name="favoriteFruit"
  onOpenChange={(o) => {
    if (!o) searchValue = "";
  }}
>
  <div class="relative">
    <OrangeSlice
      class="absolute start-3 top-1/2 size-6 -translate-y-1/2 text-muted-foreground"
    />
    <Combobox.Input
      oninput={(e) => (searchValue = e.currentTarget.value)}
      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"
    />
    <Combobox.Trigger class="absolute end-3 top-1/2 size-6 -translate-y-1/2">
      <CaretUpDown class="size-6 text-muted-foreground" />
    </Combobox.Trigger>
  </div>
  <Combobox.Portal>
    <Combobox.Content
      class="max-h-96 w-[var(--bits-combobox-anchor-width)] min-w-[var(--bits-combobox-anchor-width)] rounded-xl border border-muted bg-background px-1 py-3 shadow-popover outline-none"
      sideOffset={10}
    >
      <Combobox.ScrollUpButton class="flex w-full items-center justify-center">
        <CaretDoubleUp class="size-3" />
      </Combobox.ScrollUpButton>
      <Combobox.Viewport class="p-1">
        {#each filteredFruits as fruit, i (i + 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  data-[highlighted]:bg-muted"
            value={fruit.value}
            label={fruit.label}
          >
            {#snippet children({ selected })}
              {fruit.label}
              {#if selected}
                <div class="ml-auto">
                  <Check />
                </div>
              {/if}
            {/snippet}
          </Combobox.Item>
        {:else}
          <span class="block px-5 py-2 text-sm text-muted-foreground">
            No results found, try again.
          </span>
        {/each}
      </Combobox.Viewport>
      <Combobox.ScrollDownButton
        class="flex w-full items-center justify-center"
      >
        <CaretDoubleDown class="size-3" />
      </Combobox.ScrollDownButton>
    </Combobox.Content>
  </Combobox.Portal>
</Combobox.Root>

Overview

The Combobox component combines the functionality of an input field with a dropdown list of selectable options. It provides users with the ability to search, filter, and select from a predefined set of choices.

Key Features

  • Keyboard Navigation: Full support for keyboard interactions, allowing users to navigate and select options without using a mouse.
  • Customizable Rendering: Flexible architecture for rendering options, including support for grouped items.
  • Accessibility: Built with ARIA attributes and keyboard interactions to ensure screen reader compatibility and accessibility standards.
  • Portal Support: Ability to render the dropdown content in a portal, preventing layout issues in complex UI structures.

Architecture

The Combobox component is composed of several sub-components, each with a specific role:

  • Root: The main container component that manages the state and context for the combobox.
  • Input: The input field that allows users to enter search queries.
  • Trigger: The button or element that opens the dropdown list.
  • Portal: Responsible for portalling the dropdown content to the body or a custom target.
  • Group: A container for grouped items, used to group related items.
  • GroupHeading: A heading for a group of items, providing a descriptive label for the group.
  • Item: An individual item within the list.
  • Separator: A visual separator between items.
  • Content: The dropdown container that displays the items. It uses Floating UI to position the content relative to the trigger.
  • ContentStatic: An alternative to the Content component, that enables you to opt-out of Floating UI and position the content yourself.
  • Arrow: An arrow element that points to the trigger when using the Combobox.Content component.

Structure

Here's an overview of how the Combobox component is structured in code:

	<script lang="ts">
	import { Combobox } from "bits-ui";
</script>
 
<Combobox.Root>
	<Combobox.Input />
	<Combobox.Trigger />
	<Combobox.Portal>
		<Combobox.Content>
			<Combobox.Group>
				<Combobox.GroupHeading />
				<Combobox.Item />
			</Combobox.Group>
			<Combobox.Item />
		</Combobox.Content>
	</Combobox.Portal>
</Combobox.Root>

Reusable Components

It's recommended to use the Combobox primitives to build your own custom combobox component that can be reused throughout your application.

CustomCombobox.svelte
	<script lang="ts">
	import { Combobox, type WithoutChildrenOrChild, mergeProps } from "bits-ui";
 
	type Item = { value: string; label: string };
 
	type Props = Combobox.RootProps & {
		items: Item[];
		inputProps?: WithoutChildrenOrChild<Combobox.InputProps>;
		contentProps?: WithoutChildrenOrChild<Combobox.ContentProps>;
	};
 
	let {
		items,
		value = $bindable(),
		open = $bindable(false),
		inputProps,
		contentProps,
		...restProps
	}: Props = $props();
 
	let searchValue = $state("");
 
	const filteredItems = $derived.by(() => {
		if (searchValue === "") return items;
		return items.filter((item) => item.label.toLowerCase().includes(searchValue.toLowerCase()));
	});
 
	function handleInput(e: Event & { currentTarget: HTMLInputElement }) {
		searchValue = e.currentTarget.value;
	}
 
	function handleOpenChange(newOpen: boolean) {
		if (!newOpen) searchValue = "";
	}
 
	const mergedRootProps = $derived(mergeProps(restProps, { onOpenChange: handleOpenChange }));
	const mergedInputProps = $derived(mergeProps(inputProps, { oninput: handleInput }));
</script>
 
<Combobox.Root bind:value bind:open {...mergedRootProps}>
	<Combobox.Input {...mergedInputProps} />
	<Combobox.Trigger>Open</Combobox.Trigger>
	<Combobox.Portal>
		<Combobox.Content {...contentProps}>
			{#each filteredItems as item, i (i + item.value)}
				<Combobox.Item value={item.value} label={item.label}>
					{#snippet children({ selected })}
						{item.label}
						{selected ? "✅" : ""}
					{/snippet}
				</Combobox.Item>
			{:else}
				<span> No results found </span>
			{/each}
		</Combobox.Content>
	</Combobox.Portal>
</Combobox.Root>
+page.svelte
	<script lang="ts">
	import { CustomCombobox } from "$lib/components";
 
	const items = [
		{ value: "mango", label: "Mango" },
		{ value: "watermelon", label: "Watermelon" },
		{ value: "apple", label: "Apple" },
		// ...
	];
</script>
 
<CustomCombobox {items} />

Managing Value State

Bits UI offers several approaches to manage and synchronize the Combobox's value state, catering to different levels of control and integration needs.

1. Two-Way Binding

For seamless state synchronization, use Svelte's bind:value directive. This method automatically keeps your local state in sync with the component's internal state.

	<script lang="ts">
	import { Combobox } from "bits-ui";
	let myValue = $state("");
</script>
 
<button onclick={() => (myValue = "A")}> Select A </button>
 
<Combobox.Root bind:value={myValue}>
	<!-- ... -->
</Combobox.Root>

Key Benefits

  • Simplifies state management
  • Automatically updates myValue when the internal state changes (e.g., via clicking on an item)
  • Allows external control (e.g., selecting an item via a separate button)

2. Change Handler

For more granular control or to perform additional logic on state changes, use the onValueChange prop. This approach is useful when you need to execute custom logic alongside state updates.

	<script lang="ts">
	import { Combobox } from "bits-ui";
	let myValue = $state("");
</script>
 
<Combobox.Root
	value={myValue}
	onValueChange={(value) => {
		myValue = value;
		// additional logic here.
	}}
>
	<!-- ... -->
</Combobox.Root>

Use Cases

  • Implementing custom behaviors on value change
  • Integrating with external state management solutions
  • Triggering side effects (e.g., logging, data fetching)

3. Fully Controlled

For complete control over the component's value state, use the controlledValue prop. This approach requires you to manually manage the value state, giving you full control over when and how the component responds to value change events.

To implement controlled state:

  1. Set the controlledValue prop to true on the Combobox.Root component.
  2. Provide a value prop to Combobox.Root, which should be a variable holding the current state.
  3. Implement an onValueChange handler to update the state when the internal state changes.
	<script lang="ts">
	import { Combobox } from "bits-ui";
	let myValue = $state("");
</script>
 
<Combobox.Root controlledValue value={myValue} onValueChange={(v) => (myValue = v)}>
	<!-- ... -->
</Combobox.Root>

When to Use

  • Implementing complex logic
  • Coordinating multiple UI elements
  • Debugging state-related issues

Managing Open State

Bits UI offers several approaches to manage and synchronize the Combobox's open state, catering to different levels of control and integration needs.

1. Two-Way Binding

For seamless state synchronization, use Svelte's bind:open directive. This method automatically keeps your local state in sync with the component's internal state.

	<script lang="ts">
	import { Combobox } from "bits-ui";
	let myOpen = $state(false);
</script>
 
<button onclick={() => (myOpen = true)}> Open </button>
 
<Combobox.Root bind:open={myOpen}>
	<!-- ... -->
</Combobox.Root>

Key Benefits

  • Simplifies state management
  • Automatically updates myOpen when the internal state changes (e.g., via clicking on the trigger/input)
  • Allows external control (e.g., opening via a separate button)

2. Change Handler

For more granular control or to perform additional logic on state changes, use the onOpenChange prop. This approach is useful when you need to execute custom logic alongside state updates.

	<script lang="ts">
	import { Combobox } from "bits-ui";
	let myOpen = $state(false);
</script>
 
<Combobox.Root
	open={myOpen}
	onOpenChange={(o) => {
		myOpen = o;
		// additional logic here.
	}}
>
	<!-- ... -->
</Combobox.Root>

Use Cases

  • Implementing custom behaviors on open change
  • Integrating with external state management solutions
  • Triggering side effects (e.g., logging, data fetching)

3. Fully Controlled

For complete control over the component's value state, use the controlledOpen prop. This approach requires you to manually manage the value state, giving you full control over when and how the component responds to value change events.

To implement controlled state:

  1. Set the controlledOpen prop to true on the Combobox.Root component.
  2. Provide an open prop to Combobox.Root, which should be a variable holding the current state.
  3. Implement an onOpenChange handler to update the state when the internal state changes.
	<script lang="ts">
	import { Combobox } from "bits-ui";
	let myOpen = $state(false);
</script>
 
<Combobox.Root controlledOpen open={myOpen} onOpenChange={(v) => (myOpen = v)}>
	<!-- ... -->
</Combobox.Root>

When to Use

  • Implementing complex open/close logic
  • Coordinating multiple UI elements
  • Debugging state-related issues

Opt-out of Floating UI

When you use the Combobox.Content component, Bits UI uses Floating UI to position the content relative to the trigger, similar to other popover-like components.

You can opt-out of this behavior by instead using the Combobox.ContentStatic component.

	<Combobox.Root>
	<Combobox.Trigger />
	<Combobox.Input />
	<Combobox.Portal>
		<Combobox.ContentStatic>
			<Combobox.ScrollUpButton />
			<Combobox.Viewport>
				<Combobox.Item />
				<Combobox.Group>
					<Combobox.GroupHeading />
					<Combobox.Item />
				</Combobox.Group>
				<Combobox.ScrollDownButton />
			</Combobox.Viewport>
		</Combobox.ContentStatic>
	</Combobox.Portal>
</Combobox.Root>

When using this component, you'll need to handle the positioning of the content yourself. Keep in mind that using Combobox.Portal alongside Combobox.ContentStatic may result in some unexpected positioning behavior, feel free to not use the portal or work around it.

Custom Anchor

By default, the Combobox.Content is anchored to the Combobox.Trigger component, which determines where the content is positioned.

If you wish to instead anchor the content to a different element, you can pass either a selector string or an HTMLElement to the customAnchor prop of the Combobox.Content component.

	<script lang="ts">
	import { Combobox } from "bits-ui";
 
	let customAnchor = $state<HTMLElement>(null!);
</script>
 
<div bind:this={customAnchor}></div>
 
<Combobox.Root>
	<Combobox.Trigger />
	<Combobox.Input />
	<Combobox.Content {customAnchor}>
		<!-- ... -->
	</Combobox.Content>
</Combobox.Root>

What is the Viewport?

The Combobox.Viewport component is used to determine the size of the content in order to determine whether or not the scroll up and down buttons should be rendered.

If you wish to set a minimum/maximum height for the select content, you should apply it to the Combobox.Viewport component.

Scroll Up/Down Buttons

The Combobox.ScrollUpButton and Combobox.ScrollDownButton components are used to render the scroll up and down buttons when the select content is larger than the viewport.

You must use the Combobox.Viewport component when using the scroll buttons.

Native Scrolling/Overflow

If you don't want to use the scroll buttons and prefer to use the standard scrollbar/overflow behavior, you can omit the Combobox.Scroll[Up|Down]Button components and the Combobox.Viewport component.

You'll need to set a height on the Combobox.Content component and appropriate overflow styles to enable scrolling.

Scroll Lock

By default, when a user opens the Combobox, scrolling outside the content will be disabled. You can override this behavior by setting the preventScroll prop to false.

	<Combobox.Content preventScroll={false}>
	<!-- ... -->
</Combobox.Content>

Highlighted Items

The Combobox component follows the WAI-ARIA descendant pattern for highlighting items. This means that the Combobox.Input retains focus the entire time, even when navigating with the keyboard, and items are highlighted as the user navigates them.

Styling Highlighted Items

You can use the data-highlighted attribute on the Combobox.Item component to style the item differently when it is highlighted.

onHighlight / onUnhighlight

To trigger side effects when an item is highlighted or unhighlighted, you can use the onHighlight and onUnhighlight props.

	<Combobox.Item onHighlight={() => console.log('I am highlighted!')} onUnhighlight={() => console.log('I am unhighlighted!')} />
<!-- ... -->
</Combobox.Item>

Svelte Transitions

You can use the forceMount prop along with the child snippet to forcefully mount the Combobox.Content component to use Svelte Transitions or another animation library that requires more control.

	<script lang="ts">
	import { Combobox } from "bits-ui";
	import { fly } from "svelte/transition";
</script>
 
<Combobox.Content forceMount>
	{#snippet child({ props, open })}
		{#if open}
			<div {...props} transition:fly>
				<!-- ... -->
			</div>
		{/if}
	{/snippet}
</Combobox.Content>

Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content component that handles this logic if you intend to use this approach. For more information on using transitions with Bits UI components, see the Transitions documentation.

	<script lang="ts">
  import { Combobox } from "bits-ui";
  import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
  import Check from "phosphor-svelte/lib/Check";
  import OrangeSlice from "phosphor-svelte/lib/OrangeSlice";
  import CaretDoubleUp from "phosphor-svelte/lib/CaretDoubleUp";
  import CaretDoubleDown from "phosphor-svelte/lib/CaretDoubleDown";
  import { fly } from "svelte/transition";
 
  const fruits = [
    { value: "mango", label: "Mango" },
    { value: "watermelon", label: "Watermelon" },
    { value: "apple", label: "Apple" },
    { value: "pineapple", label: "Pineapple" },
    { value: "orange", label: "Orange" },
    { value: "grape", label: "Grape" },
    { value: "strawberry", label: "Strawberry" },
    { value: "banana", label: "Banana" },
    { value: "kiwi", label: "Kiwi" },
    { value: "peach", label: "Peach" },
    { value: "cherry", label: "Cherry" },
    { value: "blueberry", label: "Blueberry" },
    { value: "raspberry", label: "Raspberry" },
    { value: "blackberry", label: "Blackberry" },
    { value: "plum", label: "Plum" },
    { value: "apricot", label: "Apricot" },
    { value: "pear", label: "Pear" },
    { value: "grapefruit", label: "Grapefruit" }
  ];
 
  let searchValue = $state("");
 
  const filteredFruits = $derived(
    searchValue === ""
      ? fruits
      : fruits.filter((fruit) =>
          fruit.label.toLowerCase().includes(searchValue.toLowerCase())
        )
  );
</script>
 
<Combobox.Root
  type="single"
  name="favoriteFruit"
  onOpenChange={(o) => {
    if (!o) searchValue = "";
  }}
>
  <div class="relative">
    <OrangeSlice
      class="absolute start-3 top-1/2 size-6 -translate-y-1/2 text-muted-foreground"
    />
    <Combobox.Input
      oninput={(e) => (searchValue = e.currentTarget.value)}
      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"
    />
    <Combobox.Trigger class="absolute end-3 top-1/2 size-6 -translate-y-1/2">
      <CaretUpDown class="size-6 text-muted-foreground" />
    </Combobox.Trigger>
  </div>
  <Combobox.Portal>
    <Combobox.Content
      class="max-h-96 w-[var(--bits-combobox-anchor-width)] min-w-[var(--bits-combobox-anchor-width)] rounded-xl border border-muted bg-background px-1 py-3 shadow-popover outline-none"
      sideOffset={10}
      forceMount
    >
      {#snippet child({ props, open })}
        {#if open}
          <div {...props} transition:fly={{ duration: 300 }}>
            <Combobox.ScrollUpButton
              class="flex w-full items-center justify-center"
            >
              <CaretDoubleUp class="size-3" />
            </Combobox.ScrollUpButton>
            <Combobox.Viewport class="p-1">
              {#each filteredFruits as fruit, i (i + 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  data-[highlighted]:bg-muted"
                  value={fruit.value}
                  label={fruit.label}
                >
                  {#snippet children({ selected })}
                    {fruit.label}
                    {#if selected}
                      <div class="ml-auto">
                        <Check />
                      </div>
                    {/if}
                  {/snippet}
                </Combobox.Item>
              {:else}
                <span class="block px-5 py-2 text-sm text-muted-foreground">
                  No results found, try again.
                </span>
              {/each}
            </Combobox.Viewport>
            <Combobox.ScrollDownButton
              class="flex w-full items-center justify-center"
            >
              <CaretDoubleDown class="size-3" />
            </Combobox.ScrollDownButton>
          </div>
        {/if}
      {/snippet}
    </Combobox.Content>
  </Combobox.Portal>
</Combobox.Root>

API Reference

Combobox.Root

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

Property Type Description
type required
enum

The type of combobox.

Default: undefined
value $bindable
union

The value of the combobox. When the type is 'single', this should be a string. When the type is 'multiple', this should be an array of strings.

Default: undefined
onValueChange
function

A callback that is fired when the combobox value changes. When the type is 'single', the argument will be a string. When the type is 'multiple', the argument will be an array of strings.

Default: undefined
controlledValue
boolean

Whether or not the value is controlled or not. If true, the component will not update the value state internally, instead it will call onValueChange when it would have otherwise, and it is up to you to update the value prop that is passed to the component.

Default: false
open $bindable
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
controlledOpen
boolean

Whether or not the open state is controlled or not. If true, the component will not update the open state internally, instead it will call onOpenChange when it would have otherwise, and it is up to you to update the open prop that is passed to the component.

Default: false
disabled
boolean

Whether or not the combobox component is disabled.

Default: false
name
string

The name to apply to the hidden input element for form submission. If provided, a hidden input element will be rendered to submit the value of the combobox.

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'
loop
boolean

Whether or not the combobox menu should loop through items.

Default: false
allowDeselect
boolean

Whether or not the user can deselect the selected item by pressing it in a single select.

Default: true
items
array

Optionally provide an array of objects representing the items in the select for autofill capabilities. Only applicable to combobox's with type single

Default: undefined
children
Snippet

The children content to render.

Default: undefined

Combobox.Trigger

A button which toggles the combobox's open state.

Property Type Description
ref $bindable
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

The combobox's open state.

data-disabled
''

Present when the combobox is disabled.

data-combobox-trigger
''

Present on the trigger element.

Combobox.Content

The element which contains the combobox's items.

Property Type Description
side
enum

The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.

Default: bottom
sideOffset
number

The distance in pixels from the anchor to the floating element.

Default: 0
align
enum

The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.

Default: start
alignOffset
number

The distance in pixels from the anchor to the floating element.

Default: 0
arrowPadding
number

The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.

Default: 0
avoidCollisions
boolean

When true, overrides the side and align options to prevent collisions with the boundary edges.

Default: true
collisionBoundary
union

A boundary element or array of elements to check for collisions against.

Default: undefined
collisionPadding
union

The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.

Default: 0
sticky
enum

The sticky behavior on the align axis. 'partial' will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst 'always' will keep the content in the boundary regardless.

Default: partial
hideWhenDetached
boolean

When true, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.

Default: true
updatePositionStrategy
enum

The strategy to use when updating the position of the content. When 'optimized' the content will only be repositioned when the trigger is in the viewport. When 'always' the content will be repositioned whenever the position changes.

Default: optimized
strategy
enum

The positioning strategy to use for the floating element. When 'fixed' the element will be positioned relative to the viewport. When 'absolute' the element will be positioned relative to the nearest positioned ancestor.

Default: fixed
preventScroll
boolean

When true, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.

Default: false
customAnchor
union

Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.

Default: null
onEscapeKeydown
function

Callback fired when an escape keydown event occurs in the floating content. You can call event.preventDefault() to prevent the default behavior of handling the escape keydown event.

Default: undefined
escapeKeydownBehavior
enum

The behavior to use when an escape keydown event occurs in the floating content. 'close' will close the content immediately. 'ignore' will prevent the content from closing. 'defer-otherwise-close' will defer to the parent element if it exists, otherwise it will close the content. 'defer-otherwise-ignore' will defer to the parent element if it exists, otherwise it will ignore the interaction.

Default: close
onInteractOutside
function

Callback fired when an outside interaction event occurs, which is a pointerdown event. You can call event.preventDefault() to prevent the default behavior of handling the outside interaction.

Default: undefined
onFocusOutside
function

Callback fired when focus leaves the dismissible layer. You can call event.preventDefault() to prevent the default behavior on focus leaving the layer.

Default: undefined
interactOutsideBehavior
enum

The behavior to use when an interaction occurs outside of the floating content. 'close' will close the content immediately. 'ignore' will prevent the content from closing. 'defer-otherwise-close' will defer to the parent element if it exists, otherwise it will close the content. 'defer-otherwise-ignore' will defer to the parent element if it exists, otherwise it will ignore the interaction.

Default: close
onCloseAutoFocus
function

Event handler called when auto-focusing the content as it is closed. Can be prevented.

Default: undefined
preventOverflowTextSelection
boolean

When true, prevents the text selection from overflowing the bounds of the element.

Default: true
dir
enum

The reading direction of the app.

Default: ltr
loop
boolean

Whether or not the combobox should loop through items when reaching the end.

Default: false
forceMount
boolean

Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.

Default: false
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

The combobox's open state.

data-combobox-content
''

Present on the content element.

CSS Variable Description
--bits-combobox-content-transform-origin

The transform origin of the combobox content element.

--bits-combobox-content-available-width

The available width of the combobox content element.

--bits-combobox-content-available-height

The available height of the combobox content element.

--bits-combobox-anchor-width

The width of the combobox trigger element.

--bits-combobox-anchor-height

The height of the combobox trigger element.

Combobox.ContentStatic

The element which contains the combobox's items. (Static/No Floating UI)

Property Type Description
onEscapeKeydown
function

Callback fired when an escape keydown event occurs in the floating content. You can call event.preventDefault() to prevent the default behavior of handling the escape keydown event.

Default: undefined
escapeKeydownBehavior
enum

The behavior to use when an escape keydown event occurs in the floating content. 'close' will close the content immediately. 'ignore' will prevent the content from closing. 'defer-otherwise-close' will defer to the parent element if it exists, otherwise it will close the content. 'defer-otherwise-ignore' will defer to the parent element if it exists, otherwise it will ignore the interaction.

Default: close
onInteractOutside
function

Callback fired when an outside interaction event occurs, which is a pointerdown event. You can call event.preventDefault() to prevent the default behavior of handling the outside interaction.

Default: undefined
onFocusOutside
function

Callback fired when focus leaves the dismissible layer. You can call event.preventDefault() to prevent the default behavior on focus leaving the layer.

Default: undefined
interactOutsideBehavior
enum

The behavior to use when an interaction occurs outside of the floating content. 'close' will close the content immediately. 'ignore' will prevent the content from closing. 'defer-otherwise-close' will defer to the parent element if it exists, otherwise it will close the content. 'defer-otherwise-ignore' will defer to the parent element if it exists, otherwise it will ignore the interaction.

Default: close
onOpenAutoFocus
function

Event handler called when auto-focusing the content as it is opened. Can be prevented.

Default: undefined
onCloseAutoFocus
function

Event handler called when auto-focusing the content as it is closed. Can be prevented.

Default: undefined
trapFocus
boolean

Whether or not to trap the focus within the content when open.

Default: true
preventScroll
boolean

When true, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.

Default: true
preventOverflowTextSelection
boolean

When true, prevents the text selection from overflowing the bounds of the element.

Default: true
dir
enum

The reading direction of the app.

Default: ltr
loop
boolean

Whether or not the combobox should loop through items when reaching the end.

Default: false
forceMount
boolean

Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.

Default: false
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

The combobox's open state.

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
value required
string

The value of the item.

Default: undefined
label
string

The label of the item, which is what the list will be filtered by.

Default: undefined
disabled
boolean

Whether or not the combobox item is disabled. This will prevent interaction/selection.

Default: false
onHighlight
function

A callback that is fired when the item is highlighted.

Default: undefined
onUnhighlight
function

A callback that is fired when the item is unhighlighted.

Default: undefined
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-value
string

The value of the combobox item.

data-label
string

The label of the combobox item.

data-disabled
''

Present when the item is disabled.

data-highlighted
''

Present when the item is highlighted, which is either via keyboard navigation of the menu or hover.

data-selected
''

Present when the item is selected.

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
defaultValue
string

The default value of the input. This is not a reactive prop and is only used to populate the input when the combobox is first mounted if there is already a value set.

Default: undefined
ref $bindable
HTMLInputElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

The combobox's open state.

data-disabled
''

Present when the combobox is disabled.

data-combobox-input
''

Present on the input element.

Combobox.GroupHeading

A heading for the parent combobox group. This is used to describe a group of related combobox items.

Property Type Description
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-combobox-group-heading
''

Present on the group heading element.

Combobox.Arrow

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

Property Type Description
width
number

The width of the arrow in pixels.

Default: 8
height
number

The height of the arrow in pixels.

Default: 8
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-arrow
''

Present on the arrow element.