Combobox

1. Live Preview

vanilla live preview activates on the client; source HTML keeps a readable preview island and primitive contract.

2. Installation

Install adapter-specific dependencies first, then complete setup via the installation guide. installation docs

pnpm add @nake-ui/primitives @nake-ui/adapter-vanilla @nake-ui/theme-vanilla

3. Usage

Minimal runnable usage for the current adapter.

import "@nake-ui/theme-vanilla/styles.css";
import { bindCombobox } from "@nake-ui/adapter-vanilla";

const binding = bindCombobox(nodes, items, options);
binding.destroy();

4. Examples

Multiple (chips)

Builds chips-style multiple selection on top of `bindCombobox` with custom selected-value state.

import "@nake-ui/theme-vanilla/styles.css";
import { bindCombobox } from "@nake-ui/adapter-vanilla";

const selectedValues: string[] = [];

const binding = bindCombobox(
  { root, input, listbox, options },
  registrations,
  {
    allowCustomValue: false,
    onValueCommit(value, optionId) {
      if (optionId === null) {
        return;
      }

      const index = selectedValues.indexOf(value);

      if (index >= 0) {
        selectedValues.splice(index, 1);
      } else {
        selectedValues.push(value);
      }

      input.value = "";
      binding.controller.setInputValue("");
      binding.sync();
    }
  }
);

input.setAttribute("aria-label", "Search fruits");

Clear Button

A right-side clear button resets query and keeps combobox ready for the next search.

import "@nake-ui/theme-vanilla/styles.css";
import { bindCombobox } from "@nake-ui/adapter-vanilla";

const binding = bindCombobox({ root, input, listbox, options }, registrations);

clearButton.addEventListener("click", () => {
  input.value = "";
  binding.controller.setInputValue("");
  input.focus();
  binding.controller.setOpen(false);
  binding.sync();
});

clearButton.setAttribute("aria-label", "Clear selected option");

Groups

Organizes grouped options with native `role=group` and `role=separator`.

import "@nake-ui/theme-vanilla/styles.css";
import { bindCombobox } from "@nake-ui/adapter-vanilla";

const binding = bindCombobox({ root, input, listbox, options }, registrations, {
  onValueCommit() {
    binding.controller.setOpen(false);
    binding.sync();
  }
});

trigger.setAttribute("aria-label", "Open options list");

Invalid

Marks invalid input state via `aria-invalid` and `aria-describedby`.

import "@nake-ui/theme-vanilla/styles.css";
import { bindCombobox } from "@nake-ui/adapter-vanilla";

const helperId = "combobox-invalid-help";
const binding = bindCombobox({ root, input, listbox, options }, registrations);

input.setAttribute("aria-invalid", "true");
input.setAttribute("aria-describedby", helperId);

helper.textContent = "Please choose a valid fruit option.";
binding.sync();

Disabled

Disables input/trigger so the combobox stays non-interactive.

import "@nake-ui/theme-vanilla/styles.css";
import { bindCombobox } from "@nake-ui/adapter-vanilla";

// Disabled input/trigger keeps the combobox non-interactive.
input.disabled = true;
trigger.disabled = true;
input.placeholder = "Combobox is disabled";

const binding = bindCombobox({ root, input, listbox, options }, registrations);
binding.sync();

Custom Option

Renders rich option content (main text + description) while keeping committed values stable.

import "@nake-ui/theme-vanilla/styles.css";
import { bindCombobox } from "@nake-ui/adapter-vanilla";

const registrations = optionsData.map((option) => ({
  id: option.id,
  label: option.label,
  value: option.value
}));

const binding = bindCombobox({ root, input, listbox, options }, registrations);
input.placeholder = "Pick an item";
binding.sync();

Auto Highlight

With `autoHighlight`, filtering automatically highlights the first match.

import "@nake-ui/theme-vanilla/styles.css";
import { bindCombobox } from "@nake-ui/adapter-vanilla";

const binding = bindCombobox(
  { root, input, listbox, options },
  registrations,
  { autoHighlight: true }
);

input.placeholder = "Type to filter";
binding.sync();

Popup

Uses a button trigger and places the search input inside the popup panel.

import "@nake-ui/theme-vanilla/styles.css";
import { bindCombobox } from "@nake-ui/adapter-vanilla";

const binding = bindCombobox({ root, input, listbox, options }, registrations, {
  closeOnOutsidePointerDown: true
});

trigger.addEventListener("click", () => {
  binding.controller.setOpen(!binding.controller.getOpen());
  binding.sync();
});

trigger.textContent = "Choose item";

Input Group

Adds an input addon prefix without changing combobox semantics.

import "@nake-ui/theme-vanilla/styles.css";
import { bindCombobox } from "@nake-ui/adapter-vanilla";

const binding = bindCombobox({ root, input, listbox, options }, registrations);
addon.textContent = "SKU";
binding.sync();

5. RTL

The same structure running inside a `dir="rtl"` container.