Combobox

Flexible and accessible combobox component with keyboard navigation support. Built on top of Dropdown and Popover modules.

Installation

Import

import { Combobox } from '@svelte-atoms/core';

Preset Configuration

Customize the combobox appearance using presets

You can customize the default styles for Combobox components by defining presets in your configuration:

Examples

Explore different combobox variations and use cases

Basic Combobox

Simple combobox with single selection

Code

<script lang="ts">
  import { Combobox } from '@svelte-atoms/core';
  import { Input } from '@svelte-atoms/core';

  let value = $state<string | undefined>();
  let label = $state<string | undefined>();
  
  const options = [
    { value: 'option1', label: 'Option 1' },
    { value: 'option2', label: 'Option 2' },
    { value: 'option3', label: 'Option 3' }
  ];
</script>

<Combobox.Root bind:value bind:label>
  <Combobox.Trigger base={Input.Root}>
    <Combobox.Control placeholder="Select an option..." />
  </Combobox.Trigger>

  <Combobox.Content>
    {#each options as option (option.value)}
      <Combobox.Item value={option.value}>{option.label}</Combobox.Item>
    {/each}
  </Combobox.Content>
</Combobox.Root>

Multiple Selection

Combobox with multiple selection support. Supports selecting from list items and creating custom entries by pressing Enter when in multiple mode.

Code

<script lang="ts">
  import { Combobox } from '@svelte-atoms/core';
  import { Input } from '@svelte-atoms/core';

  let values = $state<string[]>([]);
  let labels = $state<string[]>([]);
  
  const options = [
    { value: 'option1', label: 'Option 1' },
    { value: 'option2', label: 'Option 2' },
    { value: 'option3', label: 'Option 3' }
  ];
</script>

<Combobox.Root bind:values bind:labels multiple>
  <Combobox.Trigger base={Input.Root} class="flex h-auto min-h-10 flex-col items-start gap-2">
    <Combobox.Control placeholder="Select multiple options..." />
    <Combobox.Selections />
  </Combobox.Trigger>

  <Combobox.Content>
    {#each options as option (option.value)}
      <Combobox.Item value={option.value}>{option.label}</Combobox.Item>
    {/each}
  </Combobox.Content>
</Combobox.Root>

With Filtering

Combobox with search/filter functionality using the Query component and filterDropdownData helper

Code

<script lang="ts">
  import { Combobox } from '@svelte-atoms/core';
  import { Input, Divider } from '@svelte-atoms/core';
  import { filterDropdownData } from '@svelte-atoms/core/components/dropdown';

  let value = $state<string | undefined>();
  let label = $state<string | undefined>();
  
  let currencies = [
    { value: 'usd', label: 'US Dollar' },
    { value: 'eur', label: 'Euro' },
    { value: 'gbp', label: 'British Pound' }
  ];

  const filteredItems = filterDropdownData(
    () => currencies,
    (query, item) => item.label.toLowerCase().includes(query.toLowerCase())
  );
</script>

<Combobox.Root bind:value bind:label>
  <Combobox.Trigger base={Input.Root}>
    <Input.Icon class="text-foreground/50">$</Input.Icon>
    <Divider vertical class="mx-1" />
    <Combobox.Control placeholder="Select a currency..." />
  </Combobox.Trigger>

  <Combobox.Content>
    <input 
      bind:value={filteredItems.query} 
      class="border-border border-b px-4 py-3"
      placeholder="Type to filter..." 
    />
    {#each filteredItems.current as item (item.value)}
      <Combobox.Item value={item.value}>{item.label}</Combobox.Item>
    {/each}
  </Combobox.Content>
</Combobox.Root>

API Reference

Combobox.Root Props

Prop

Type

Default

Description

open

boolean | undefined

false

Open

value

unknown

undefined

Value

values

unknown[] | undefined

undefined

Values

label

string | undefined

Label

labels

string[] | undefined

Labels

multiple

boolean | undefined

false

Multiple

disabled

boolean | undefined

false

Disabled

placements

string[] | undefined

Placements

placement

string | undefined

Placement

offset

number | undefined

Offset

factory

Factory<ComboboxBond> | undefined

undefined

Factory

children

Snippet<[{ combobox: ComboboxBond; }]> | undefined

undefined

Children content snippet

...atomProps

HtmlAtomProps

All HTML element props are supported. See [Atom Props](/docs/components/atom#props) for the complete list of inherited properties.

Combobox.Trigger Props

Inherits all props from the base component (typically Input.Root). Common props include class, as, and base.

Combobox.Item Props

Re-exported from Dropdown.Item. See Dropdown component documentation for full props list. Key props include value (string), data (custom data), and preset ('dropdown.item').

Combobox.Control Props

Prop

Type

Default

Description

value

any

undefined

The input value

files

File[]

undefined

File list for file inputs

date

Date | null

null

Date value for date inputs

number

undefined

Number value for number inputs

checked

boolean

undefined

Checked state for checkbox/radio inputs

type

HTMLInputTypeAttribute | null

'text'

HTML input type attribute

placeholder

string

undefined

Placeholder text for the input

class

string

undefined

CSS class for the input control

children

Snippet

undefined

Children content snippet

bond

Bond

undefined

Bond object for component communication

base

Component | Snippet

undefined

Base component or snippet to render

preset

PresetModuleName | string

'input.control'

Preset module name for styling

variants

VariantDefinition | Function

undefined

Variant definition or function to resolve variants

string

undefined

HTML tag to render as

global

boolean

false

Whether to use global styles

initial

NodeFunction

undefined

Function called on initial render

enter

TransitionFunction

undefined

Transition function for entering

exit

TransitionFunction

undefined

Transition function for exiting

animate

NodeFunction

undefined

Animation function

onmount

NodeFunction

undefined

Function called when element is mounted

ondestroy

NodeFunction

undefined

Function called when element is destroyed

Combobox.Selections Props

Prop

Type

Default

Description

class

ClassValue | undefined

undefined

CSS class for the selections container

Selection

Component<{}, {}, string> | undefined

Selection

children

Snippet<[{ selections: DropdownSelection[]; selection?: DropdownSelection | undefined; }]> | undefined

undefined

Children content snippet

getSelections

(<T extends DropdownBond>(bond: T) => DropdownSelection[]) | undefined

undefined

Custom function to retrieve selections from the bond

Combobox.Selection Props

Prop

Type

Default

Description

selection

DropdownSelection

Selection object containing id, value, label, and unselect function (required)

children

Snippet<[]> | undefined

undefined

Children content snippet

onclose

((event: Event) => void) | undefined

undefined

Callback fired when the selection is closed/removed

...atomProps

HtmlAtomProps

All HTML element props are supported. See [Atom Props](/docs/components/atom#props) for the complete list of inherited properties.

Available Components

Combobox.Root - Main combobox container (manages state)
Combobox.Trigger - Trigger element (typically composed with Input.Root using base prop)
Combobox.Control - Input control for filtering and displaying selected value
Combobox.Item - Individual selectable combobox item
Combobox.Selections - Container for displaying selected items (multi-select mode)
Combobox.Arrow - Popover arrow indicator (re-exported from Dropdown)
Combobox.Indicator - Custom indicator element (re-exported from Dropdown)
Combobox.Content - List container for items (re-exported from Dropdown)
Combobox.Group - Group container for items (re-exported from Dropdown)
Combobox.Divider - Visual divider between items (re-exported from Dropdown)
Combobox.Title - Title element for groups (re-exported from Dropdown)
Combobox.Selection - Individual selection badge/chip (re-exported from Dropdown)
Combobox.Placeholder - Placeholder element (re-exported from Dropdown)

Helper Functions

filterDropdownData

A reactive helper function for filtering dropdown/combobox data based on a query string.

Accessibility

Built-in Accessibility Features

• Full ARIA attributes support with proper roles (combobox, listbox, option)
• Keyboard navigation (Arrow keys to navigate, Escape to close, Enter to select)
• Screen reader announcements for selection changes
• Focus management with proper focus trapping
• aria-activedescendant for highlighted items
• aria-multiselectable for multiple selection mode
• Proper labeling and descriptions

Collapsible

Context Menu