Skip to content
Melt UI

Combobox

Presents a selection of choices to the user, filtered by a text input.

Props

Features

Section titled “Features”
  • 🎹 Keyboard navigation
  • 🍃 Multi-selection mode
  • 🧠 Smart focus management
  • 💬 Flexible filtering

Usage

Section titled “Usage”
<script lang="ts">
  import { Combobox } from "melt/builders";


  const options = [  /* ... */  ] as const;
  type Option = (typeof options)[number];


  const combobox = new Combobox<Option>();


  const filtered = $derived.by(() => {
    if (!combobox.touched) return options;
    return options.filter((o) =>
      o.toLowerCase().includes(combobox.inputValue.trim().toLowerCase()),
    );
  });
</script>


<label {...combobox.label}>Favorite Character</label>
<input {...combobox.input} />
<button {...combobox.trigger}>open</button>


<div {...combobox.content}>
  {#each filtered as option (option)}
    <div {...combobox.getOption(option)}>
      {option}
      {#if combobox.isSelected(option)}
        ✓
      {/if}
    </div>
  {:else}
    <span>No results found</span>
  {/each}
</div>

Customizing floating elements

Section titled “Customizing floating elements”

Floating elements use Floating UI under the hood. To this end, we expose a floatingConfig option, which can be used to control the underlying computePosition function, its middlewares, and the resulting styling that is applied.

API Reference

Section titled “API Reference”

Constructor Props

The props that are passed when calling 
new Combobox()
    export type ComboboxProps<T, Multiple extends boolean = false> = Omit<
      PopoverProps,
      "closeOnEscape" | "closeOnOutsideClick" | "sameWidth"
    > & {
      /**
       * If `true`, multiple options can be selected at the same time.
       *
       * @default false
       */
      multiple?: MaybeGetter<Multiple | undefined>;
    

      /**
       * The value for the Combobox.
       *
       * When passing a getter, it will be used as source of truth,
       * meaning that the value only changes when the getter returns a new value.
       *
       * Otherwise, if passing a static value, it'll serve as the default value.
       *
       *
       * @default false
       */
      value?: MaybeMultiple<T, Multiple>;
      /**
       * Called when the value is supposed to change.
       */
      onValueChange?: OnMultipleChange<T, Multiple>;
    

      /**
       * The inputValue for the Combobox.
       *
       * When passing a getter, it will be used as source of truth,
       * meaning that the value only changes when the getter returns a new value.
       *
       * Otherwise, if passing a static value, it'll serve as the default value.
       *
       *
       * @default false
       */
      inputValue?: MaybeGetter<string | undefined>;
      /**
       * Called when the value is supposed to change.
       */
      onInputValueChange?: Setter<string>;
    

      /**
       * The currently highlighted value.
       */
      highlighted?: MaybeGetter<T | null | undefined>;
    

      /**
       * Called when the highlighted value changes.
       */
      onHighlightChange?: (highlighted: T | null) => void;
    

      /**
       * Determines behavior when scrolling items into view.
       * Set to null to disable auto-scrolling.
       *
       * @default "nearest"
       * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView#block
       */
      scrollAlignment?: MaybeGetter<"nearest" | "center" | null | undefined>;
    

      /**
       * If the content should have the same width as the trigger
       *
       * @default true
       */
      sameWidth?: MaybeGetter<boolean | undefined>;
    };

Methods

The methods returned from 
new Combobox()

  • select 

    (value: T) => void

  • scrollIntoView 

    (value?: T | undefined) => void

  • getOptionId 

    (value: T) => string

  • getOption 

    (
      value: T,
      label?: string | undefined,
      onSelect?: (() => void) | undefined,
    ) => {
      readonly id: string
      readonly "data-melt-combobox-option": ""
      readonly "data-value": string
      readonly "data-label": string
      readonly "aria-hidden": true | undefined
      readonly "aria-selected": boolean
      readonly "data-highlighted": "" | undefined
      readonly tabindex: -1
      readonly role: "option"
      readonly onmouseover: () => void
      readonly onclick: () => void
    }
    Gets the attributes for the option element. @param value The value of the option. @param label The label to display for the option. If not provided, the value will be stringified. @param onSelect An optional callback to call when the option is selected, overriding the default behavior. @returns The attributes for the option element.

  • getOptionsEls 

    () => HTMLElement[]

  • getOptions 

    () => T[]

  • highlight 

    (value: T) => void

  • highlightNext 

    () => void

  • highlightPrev 

    () => void

  • highlightFirst 

    () => void

  • highlightLast 

    () => void

Properties

The properties returned from 
new Combobox()

  • multiple 

    Multiple

  • scrollAlignment 

    "nearest" | "center" | null

  • touched 

    boolean

  • onSelectMap 

    Map<T, () => void>

  • ids 

    {
      trigger: string
      content: string
      option: string
      input: string
    } & { popover: string }

  • isSelected 

    (value: T) => boolean

  • getOptionLabel 

    (value: T) => string

  • value 

    SelectionStateValue<T, Multiple>

  • inputValue 

    string

  • highlighted 

    T | null

  • label 

    {
      for: string
      onclick: (
        e: MouseEvent & { currentTarget: EventTarget & HTMLLabelElement },
      ) => void
    }

  • input 

    {
      readonly "data-melt-combobox-input": ""
      readonly id: string
      readonly role: "combobox"
      readonly "aria-expanded": boolean
      readonly "aria-controls": string
      readonly "aria-owns": string
      readonly onclick: () => void
      readonly value: string
      readonly oninput: (e: Event) => void
      readonly onkeydown: (e: KeyboardEvent) => void
      readonly onfocus: (event: FocusEvent) => void
      readonly onfocusout: (event: FocusEvent) => Promise<void>
      readonly style: `--melt-invoker-width: ${string}; --melt-invoker-height: ${string}; --melt-invoker-x: ${string}; --melt-invoker-y: ${string}; --melt-popover-available-width: ${string}; --melt-popover-available-height: ${string}`
      readonly popovertarget: string
    }

  • trigger 

    {
      onfocus: (event: FocusEvent) => void
      onfocusout: (event: FocusEvent) => Promise<void>
      style: `--melt-invoker-width: ${string}; --melt-invoker-height: ${string}; --melt-invoker-x: ${string}; --melt-invoker-y: ${string}; --melt-popover-available-width: ${string}; --melt-popover-available-height: ${string}`
      "data-melt-combobox-trigger": string
      id: string
      onclick: () => void
    }

  • content 

    {
      readonly onfocus: (event: FocusEvent) => void
      readonly onfocusout: (event: FocusEvent) => Promise<void>
      readonly style: `--melt-invoker-width: ${string}; --melt-invoker-height: ${string}; --melt-invoker-x: ${string}; --melt-invoker-y: ${string}; --melt-popover-available-width: ${string}; --melt-popover-available-height: ${string}`
      readonly id: string
      readonly popover: "manual"
      readonly ontoggle: (
        e: ToggleEvent & { currentTarget: EventTarget & HTMLElement },
      ) => void
      readonly tabindex: -1
      readonly inert: boolean
      readonly "data-open": "" | undefined
    } & {
      readonly "data-melt-combobox-content": ""
      readonly role: "listbox"
      readonly "aria-expanded": boolean
      readonly "aria-activedescendant": string | undefined
    }

  • valueAsString 

    string