Combobox

A custom select: a role="combobox" text field that opens a filtered ListBox in a Popover. It pairs three existing primitives — the Input shell, the Popover positioning layer, and the ListBox option engine — behind one headless connectCombobox core, so the same component supports single and multiple selection, typeahead search, a clear button, and creatable values.

Unlike the standalone ListBox (which moves DOM focus between options with a roving tabindex), the Combobox keeps focus on the input and drives the list with aria-activedescendant (the ListBox’s focusStrategy="active-descendant" mode). The input owns the keyboard; the popup just reflects the cursor.

Default

Single selection. Type to filter, arrow keys to move the cursor (focus stays in the input), Enter to commit. Selecting an option fills the field with its label and closes the popup.

AstroReactSvelteVue

PreviewCode

---
import Combobox from "../combobox.astro";
import { stack } from "@pindoba/styled-system/patterns";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue" },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular" },
  { id: "qwik", label: "Qwik" },
];
---

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox
    id="astro-cb-default"
    items={items}
    aria-label="Framework"
    placeholder="Search a framework…"
  />
</div>

Selected: none

import { Combobox } from "../Combobox";
import { stack } from "@pindoba/styled-system/patterns";
import type { Key } from "@pindoba/core-combobox";
import React, { useState } from "react";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue" },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular" },
  { id: "qwik", label: "Qwik" },
];

export default function DefaultDemo() {
  const [selected, setSelected] = useState<Key | null>(null);

  return (
    <div className={stack({ gap: "sm", alignItems: "flex-start" })}>
      <Combobox
        items={items}
        aria-label="Framework"
        placeholder="Search a framework…"
        value={selected}
        onValueChange={(value) => setSelected(value as Key | null)}
      />
      <p>Selected: {selected ?? "none"}</p>
    </div>
  );
}

Selected: none

<script lang="ts">
  import Combobox from "../combobox.svelte";
  import { stack } from "@pindoba/styled-system/patterns";
  import type { Key } from "@pindoba/core-combobox";

  const items = [
    { id: "react", label: "React" },
    { id: "svelte", label: "Svelte" },
    { id: "vue", label: "Vue" },
    { id: "solid", label: "Solid" },
    { id: "angular", label: "Angular" },
    { id: "qwik", label: "Qwik" },
  ];

  let selected = $state<Key | null>(null);
</script>

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox
    {items}
    aria-label="Framework"
    placeholder="Search a framework…"
    bind:value={selected}
  />
  <p>Selected: {selected ?? "none"}</p>
</div>

Selected: none

<script setup lang="ts">
import { ref } from "vue";
import { Combobox } from "@pindoba/vue-combobox";
import type { Key, ComboboxValue } from "@pindoba/core-combobox";
import { stack } from "@pindoba/styled-system/patterns";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue" },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular" },
  { id: "qwik", label: "Qwik" },
];

const selected = ref<Key | null>(null);

function onValueChange(value: ComboboxValue) {
  selected.value = (value as Key | null) ?? null;
}
</script>

<template>
  <div :class="stack({ gap: 'sm', alignItems: 'flex-start' })">
    <Combobox
      :items="items"
      aria-label="Framework"
      placeholder="Search a framework…"
      :value="selected"
      :onValueChange="onValueChange"
    />
    <p>Selected: {{ selected ?? "none" }}</p>
  </div>
</template>

Multiple selection

Set selectionMode="multiple". Each chosen value renders as a removable chip (Group → Badge + a dismiss Button) inside the field; the popup stays open and the query clears after each pick. Backspace on an empty query removes the last chip.

AstroReactSvelteVue

PreviewCode

Svelte

---
import Combobox from "../combobox.astro";
import { stack } from "@pindoba/styled-system/patterns";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue" },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular" },
];
---

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox
    id="astro-cb-multi"
    items={items}
    selectionMode="multiple"
    defaultValue={["svelte"]}
    aria-label="Frameworks"
    placeholder="Pick frameworks…"
  />
</div>

Svelte

Selected: svelte

import { Combobox } from "../Combobox";
import { stack } from "@pindoba/styled-system/patterns";
import type { Key } from "@pindoba/core-combobox";
import React, { useState } from "react";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue" },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular" },
];

export default function MultiSelectDemo() {
  const [selected, setSelected] = useState<Key[]>(["svelte"]);

  return (
    <div className={stack({ gap: "sm", alignItems: "flex-start" })}>
      <Combobox
        items={items}
        selectionMode="multiple"
        aria-label="Frameworks"
        placeholder="Pick frameworks…"
        value={selected}
        onValueChange={(value) => setSelected((value as Key[]) ?? [])}
      />
      <p>Selected: {selected.join(", ") || "none"}</p>
    </div>
  );
}

Svelte

Selected: svelte

<script lang="ts">
  import Combobox from "../combobox.svelte";
  import { stack } from "@pindoba/styled-system/patterns";
  import type { Key } from "@pindoba/core-combobox";

  const items = [
    { id: "react", label: "React" },
    { id: "svelte", label: "Svelte" },
    { id: "vue", label: "Vue" },
    { id: "solid", label: "Solid" },
    { id: "angular", label: "Angular" },
  ];

  let selected = $state<Key[]>(["svelte"]);
</script>

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox
    {items}
    selectionMode="multiple"
    aria-label="Frameworks"
    placeholder="Pick frameworks…"
    bind:value={selected}
  />
  <p>Selected: {selected.join(", ") || "none"}</p>
</div>

Svelte

Selected: svelte

<script setup lang="ts">
import { ref } from "vue";
import { Combobox } from "@pindoba/vue-combobox";
import type { Key, ComboboxValue } from "@pindoba/core-combobox";
import { stack } from "@pindoba/styled-system/patterns";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue" },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular" },
];

const selected = ref<Key[]>(["svelte"]);

function onValueChange(value: ComboboxValue) {
  selected.value = (value as Key[]) ?? [];
}
</script>

<template>
  <div :class="stack({ gap: 'sm', alignItems: 'flex-start' })">
    <Combobox
      :items="items"
      selectionMode="multiple"
      aria-label="Frameworks"
      placeholder="Pick frameworks…"
      :value="selected"
      :onValueChange="onValueChange"
    />
    <p>Selected: {{ selected.join(", ") || "none" }}</p>
  </div>
</template>

Sizes

size (sm · md · lg) sets the field height to the matching control.<size> — identical to Input and every other control. The field stays exactly that tall in every state, chips included; the chips themselves scale a tier with the size so they stay proportionate rather than floating small in a taller field.

AstroReactSvelteVue

PreviewCode

Svelte

React

Svelte

React

---
import Combobox from "../combobox.astro";
import { stack } from "@pindoba/styled-system/patterns";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue" },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular" },
];

// Each field stays exactly `control.<size>` tall; the chips scale with it.
const sizes = ["sm", "md", "lg"] as const;
const seed: Record<(typeof sizes)[number], string[]> = {
  sm: ["svelte"],
  md: ["svelte", "react"],
  lg: ["svelte", "react"],
};
---

<div class={stack({ gap: "md", alignItems: "flex-start", width: "100%" })}>
  {
    sizes.map((size) => (
      <Combobox
        id={`astro-cb-sizes-${size}`}
        items={items}
        size={size}
        selectionMode="multiple"
        chipOverflow={false}
        defaultValue={seed[size]}
        aria-label={`Frameworks (${size})`}
        placeholder={`Pick frameworks (${size})…`}
      />
    ))
  }
</div>

Svelte

React

Svelte

React

import { Combobox } from "../Combobox";
import { stack } from "@pindoba/styled-system/patterns";
import type { Key } from "@pindoba/core-combobox";
import React, { useState } from "react";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue" },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular" },
];

const sizes = ["sm", "md", "lg"] as const;

// Each field stays exactly `control.<size>` tall; the chips scale with it.
export default function SizesDemo() {
  const [selected, setSelected] = useState<
    Record<(typeof sizes)[number], Key[]>
  >({ sm: ["svelte"], md: ["svelte", "react"], lg: ["svelte", "react"] });

  return (
    <div
      className={stack({ gap: "md", alignItems: "flex-start", width: "100%" })}
    >
      {sizes.map((size) => (
        <Combobox
          key={size}
          items={items}
          size={size}
          selectionMode="multiple"
          chipOverflow={false}
          aria-label={`Frameworks (${size})`}
          placeholder={`Pick frameworks (${size})…`}
          value={selected[size]}
          onValueChange={(value) =>
            setSelected((prev) => ({ ...prev, [size]: (value as Key[]) ?? [] }))
          }
        />
      ))}
    </div>
  );
}

Svelte

React

Svelte

React

<script lang="ts">
  import Combobox from "../combobox.svelte";
  import { stack } from "@pindoba/styled-system/patterns";
  import type { Key } from "@pindoba/core-combobox";

  const items = [
    { id: "react", label: "React" },
    { id: "svelte", label: "Svelte" },
    { id: "vue", label: "Vue" },
    { id: "solid", label: "Solid" },
    { id: "angular", label: "Angular" },
  ];

  // Each field stays exactly `control.<size>` tall; the chips scale with it.
  const sizes = ["sm", "md", "lg"] as const;
  let selected = $state<Record<(typeof sizes)[number], Key[]>>({
    sm: ["svelte"],
    md: ["svelte", "react"],
    lg: ["svelte", "react"],
  });
</script>

<div class={stack({ gap: "md", alignItems: "flex-start", width: "100%" })}>
  {#each sizes as size (size)}
    <Combobox
      {items}
      {size}
      selectionMode="multiple"
      chipOverflow={false}
      aria-label={`Frameworks (${size})`}
      placeholder={`Pick frameworks (${size})…`}
      bind:value={selected[size]}
    />
  {/each}
</div>

Svelte

React

Svelte

React

<script setup lang="ts">
import { ref } from "vue";
import { Combobox } from "@pindoba/vue-combobox";
import type { Key, ComboboxValue } from "@pindoba/core-combobox";
import { stack } from "@pindoba/styled-system/patterns";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue" },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular" },
];

// Each field stays exactly `control.<size>` tall; the chips scale with it.
const sizes = ["sm", "md", "lg"] as const;
type Size = (typeof sizes)[number];

const selected = ref<Record<Size, Key[]>>({
  sm: ["svelte"],
  md: ["svelte", "react"],
  lg: ["svelte", "react"],
});

function onValueChange(size: Size, value: ComboboxValue) {
  selected.value = { ...selected.value, [size]: (value as Key[]) ?? [] };
}
</script>

<template>
  <div :class="stack({ gap: 'md', alignItems: 'flex-start', width: '100%' })">
    <Combobox
      v-for="size in sizes"
      :key="size"
      :items="items"
      :size="size"
      selectionMode="multiple"
      :chipOverflow="false"
      :aria-label="`Frameworks (${size})`"
      :placeholder="`Pick frameworks (${size})…`"
      :value="selected[size]"
      :onValueChange="(value: ComboboxValue) => onValueChange(size, value)"
    />
  </div>
</template>

Chip overflow

When many values are selected the chip row can grow taller than the field has room for. Cap it with chipOverflow (defaults to 1):

chipOverflow={n} — keep the last n chips inline and collapse the rest behind a “+N” chip. (Last, not first, so the most-recent chip stays next to the input and Backspace still deletes it.)
chipOverflow="auto" — measure the field and fit as many chips as the width allows. Best with a constrained width (fullWidth or a max-width); resize the second field below to watch it adapt.
chipOverflow={false} — disable collapsing entirely: every selected chip renders inline and the field grows to fit them.

The “+N” chip is a Badge plus a chevron Button (like the closable chip). The chevron opens a popover listing the collapsed options with a (keyboard-operable) remove button — manage the hidden selections without expanding the field. The “+N” popover and the options dropdown are mutually exclusive: opening one closes the other.

Long labels can be trimmed independently of overflow: chipMaxChars={n} truncates to n characters (the full label stays in the chip’s title and in the popover), and chipMaxWidth="8rem" caps the chip width with an ellipsis. They compose.

AstroReactSvelteVue

PreviewCode

Fixed — last 1 inline, "+N" for the rest, labels capped at 10 chars

Angular

Auto — fit chips to the field width (resize the box), 8rem cap

React

Svelte

Vue

Ember.js (…

---
import Combobox from "../combobox.astro";
import { stack } from "@pindoba/styled-system/patterns";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue" },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular" },
  { id: "qwik", label: "Qwik" },
  { id: "ember", label: "Ember.js (with a deliberately long label)" },
  { id: "preact", label: "Preact" },
];

const fill = { root: { style: { width: "100%" } } };
---

<div class={stack({ gap: "lg", alignItems: "flex-start" })}>
  <div class={stack({ gap: "2xs", alignItems: "flex-start" })}>
    <span
      >Fixed — last 1 inline, "+N" for the rest, labels capped at 10 chars</span
    >
    <div style="width: 360px; max-width: 100%;">
      <Combobox
        id="astro-cb-overflow-fixed"
        items={items}
        selectionMode="multiple"
        chipOverflow={1}
        chipMaxChars={10}
        defaultValue={["react", "svelte", "vue", "solid", "angular"]}
        aria-label="Frameworks (fixed overflow)"
        placeholder="Pick frameworks…"
        passThrough={fill}
      />
    </div>
  </div>

  <div class={stack({ gap: "2xs", alignItems: "flex-start" })}>
    <span>Auto — fit chips to the field width (resize the box), 8rem cap</span>
    <!-- `resize` needs a non-visible overflow; the padding keeps that clip off
         the field's focus ring. -->
    <div
      style="resize: horizontal; overflow: hidden; width: 440px; max-width: 100%; padding: 8px;"
    >
      <Combobox
        id="astro-cb-overflow-auto"
        items={items}
        selectionMode="multiple"
        chipOverflow="auto"
        chipMaxWidth="8rem"
        defaultValue={["react", "svelte", "vue", "ember"]}
        aria-label="Frameworks (auto overflow)"
        placeholder="Pick frameworks…"
        passThrough={fill}
      />
    </div>
  </div>
</div>

Fixed — last 1 inline, "+N" for the rest, labels capped at 10 chars

Angular

Auto — fit chips to the field width (resize the box), 8rem cap

React

Svelte

Vue

Ember.js (…

import { Combobox } from "../Combobox";
import { stack } from "@pindoba/styled-system/patterns";
import type { Key } from "@pindoba/core-combobox";
import React, { useState } from "react";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue" },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular" },
  { id: "qwik", label: "Qwik" },
  { id: "ember", label: "Ember.js (with a deliberately long label)" },
  { id: "preact", label: "Preact" },
];

const fill = { root: { style: { width: "100%" } } };

export default function ChipOverflowDemo() {
  const [fixed, setFixed] = useState<Key[]>([
    "react",
    "svelte",
    "vue",
    "solid",
    "angular",
  ]);
  const [auto, setAuto] = useState<Key[]>(["react", "svelte", "vue", "ember"]);

  return (
    <div className={stack({ gap: "lg", alignItems: "flex-start" })}>
      <div className={stack({ gap: "2xs", alignItems: "flex-start" })}>
        <span>
          Fixed — last 1 inline, "+N" for the rest, labels capped at 10 chars
        </span>
        <div style={{ width: "360px", maxWidth: "100%" }}>
          <Combobox
            items={items}
            selectionMode="multiple"
            chipOverflow={1}
            chipMaxChars={10}
            aria-label="Frameworks (fixed overflow)"
            placeholder="Pick frameworks…"
            value={fixed}
            onValueChange={(value) => setFixed((value as Key[]) ?? [])}
            passThrough={fill}
          />
        </div>
      </div>

      <div className={stack({ gap: "2xs", alignItems: "flex-start" })}>
        <span>
          Auto — fit chips to the field width (resize the box), 8rem cap
        </span>
        {/* `resize` needs a non-visible overflow; the padding keeps that clip
            off the field's focus ring. */}
        <div
          style={{
            resize: "horizontal",
            overflow: "hidden",
            width: "440px",
            maxWidth: "100%",
            padding: "8px",
          }}
        >
          <Combobox
            items={items}
            selectionMode="multiple"
            chipOverflow="auto"
            chipMaxWidth="8rem"
            aria-label="Frameworks (auto overflow)"
            placeholder="Pick frameworks…"
            value={auto}
            onValueChange={(value) => setAuto((value as Key[]) ?? [])}
            passThrough={fill}
          />
        </div>
      </div>
    </div>
  );
}

Fixed — last 1 inline, "+N" for the rest, labels capped at 10 chars

Angular

Auto — fit chips to the field width (resize the box), 8rem cap

React

Svelte

Vue

Ember.js (…

<script lang="ts">
  import Combobox from "../combobox.svelte";
  import { stack } from "@pindoba/styled-system/patterns";
  import type { Key } from "@pindoba/core-combobox";

  const items = [
    { id: "react", label: "React" },
    { id: "svelte", label: "Svelte" },
    { id: "vue", label: "Vue" },
    { id: "solid", label: "Solid" },
    { id: "angular", label: "Angular" },
    { id: "qwik", label: "Qwik" },
    { id: "ember", label: "Ember.js (with a deliberately long label)" },
    { id: "preact", label: "Preact" },
  ];

  const fill = { root: { style: { width: "100%" } } };

  let fixed = $state<Key[]>(["react", "svelte", "vue", "solid", "angular"]);
  let auto = $state<Key[]>(["react", "svelte", "vue", "ember"]);
</script>

<div class={stack({ gap: "lg", alignItems: "flex-start" })}>
  <div class={stack({ gap: "2xs", alignItems: "flex-start" })}>
    <span
      >Fixed — last 1 inline, "+N" for the rest, labels capped at 10 chars</span
    >
    <div style="width: 360px; max-width: 100%;">
      <Combobox
        {items}
        selectionMode="multiple"
        chipOverflow={1}
        chipMaxChars={10}
        aria-label="Frameworks (fixed overflow)"
        placeholder="Pick frameworks…"
        bind:value={fixed}
        passThrough={fill}
      />
    </div>
  </div>

  <div class={stack({ gap: "2xs", alignItems: "flex-start" })}>
    <span>Auto — fit chips to the field width (resize the box), 8rem cap</span>
    <!-- `resize` needs a non-visible overflow; the padding keeps that clip off
         the field's focus ring. -->
    <div
      style="resize: horizontal; overflow: hidden; width: 440px; max-width: 100%; padding: 8px;"
    >
      <Combobox
        {items}
        selectionMode="multiple"
        chipOverflow="auto"
        chipMaxWidth="8rem"
        aria-label="Frameworks (auto overflow)"
        placeholder="Pick frameworks…"
        bind:value={auto}
        passThrough={fill}
      />
    </div>
  </div>
</div>

Fixed — last 1 inline, "+N" for the rest, labels capped at 10 chars

Angular

Auto — fit chips to the field width (resize the box), 8rem cap

React

Svelte

Vue

Ember.js (with a deliberately long label)

<script setup lang="ts">
import { ref } from "vue";
import { Combobox } from "@pindoba/vue-combobox";
import type { Key, ComboboxValue } from "@pindoba/core-combobox";
import { stack } from "@pindoba/styled-system/patterns";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue" },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular" },
  { id: "qwik", label: "Qwik" },
  { id: "ember", label: "Ember.js (with a deliberately long label)" },
  { id: "preact", label: "Preact" },
];

const fill = { root: { style: { width: "100%" } } };

const fixed = ref<Key[]>(["react", "svelte", "vue", "solid", "angular"]);
const auto = ref<Key[]>(["react", "svelte", "vue", "ember"]);

function onFixedChange(value: ComboboxValue) {
  fixed.value = (value as Key[]) ?? [];
}
function onAutoChange(value: ComboboxValue) {
  auto.value = (value as Key[]) ?? [];
}
</script>

<template>
  <div :class="stack({ gap: 'lg', alignItems: 'flex-start' })">
    <div :class="stack({ gap: '2xs', alignItems: 'flex-start' })">
      <span
        >Fixed — last 1 inline, "+N" for the rest, labels capped at 10
        chars</span
      >
      <div style="width: 360px; max-width: 100%">
        <Combobox
          :items="items"
          selectionMode="multiple"
          :chipOverflow="1"
          :chipMaxChars="10"
          aria-label="Frameworks (fixed overflow)"
          placeholder="Pick frameworks…"
          :value="fixed"
          :onValueChange="onFixedChange"
          :passThrough="fill"
        />
      </div>
    </div>

    <div :class="stack({ gap: '2xs', alignItems: 'flex-start' })">
      <span
        >Auto — fit chips to the field width (resize the box), 8rem cap</span
      >
      <!-- `resize` needs a non-visible overflow; the padding keeps that clip
           off the field's focus ring. -->
      <div
        style="
          resize: horizontal;
          overflow: hidden;
          width: 440px;
          max-width: 100%;
          padding: 8px;
        "
      >
        <Combobox
          :items="items"
          selectionMode="multiple"
          chipOverflow="auto"
          chipMaxWidth="8rem"
          aria-label="Frameworks (auto overflow)"
          placeholder="Pick frameworks…"
          :value="auto"
          :onValueChange="onAutoChange"
          :passThrough="fill"
        />
      </div>
    </div>
  </div>
</template>

Creatable

With allowCreate, typing a value that isn’t in the list surfaces a “Create …” row at the bottom. Committing it (click or Enter) fires onCreate so you can add the value to your data.

AstroReactSvelteVue

PreviewCode

---
import Combobox from "../combobox.astro";
import { stack } from "@pindoba/styled-system/patterns";

const items = [
  { id: "bug", label: "bug" },
  { id: "feature", label: "feature" },
  { id: "docs", label: "docs" },
];
---

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox
    id="astro-cb-creatable"
    items={items}
    selectionMode="multiple"
    allowCreate
    aria-label="Labels"
    placeholder="Add or create a label…"
  />
</div>

Selected: none

import { Combobox } from "../Combobox";
import { stack } from "@pindoba/styled-system/patterns";
import type { Key } from "@pindoba/core-combobox";
import React, { useState } from "react";

export default function CreatableDemo() {
  const [items, setItems] = useState([
    { id: "bug", label: "bug" },
    { id: "feature", label: "feature" },
    { id: "docs", label: "docs" },
  ]);
  const [selected, setSelected] = useState<Key[]>([]);

  function onCreate(value: string) {
    const id = value.toLowerCase();
    setItems((prev) =>
      prev.some((i) => i.id === id) ? prev : [...prev, { id, label: value }],
    );
    setSelected((prev) => [...prev, id]);
  }

  return (
    <div className={stack({ gap: "sm", alignItems: "flex-start" })}>
      <Combobox
        items={items}
        selectionMode="multiple"
        allowCreate
        aria-label="Labels"
        placeholder="Add or create a label…"
        value={selected}
        onValueChange={(value) => setSelected((value as Key[]) ?? [])}
        onCreate={onCreate}
      />
      <p>Selected: {selected.join(", ") || "none"}</p>
    </div>
  );
}

Selected: none

<script lang="ts">
  import Combobox from "../combobox.svelte";
  import { stack } from "@pindoba/styled-system/patterns";
  import type { Key } from "@pindoba/core-combobox";

  let items = $state([
    { id: "bug", label: "bug" },
    { id: "feature", label: "feature" },
    { id: "docs", label: "docs" },
  ]);
  let selected = $state<Key[]>([]);

  function onCreate(value: string) {
    const id = value.toLowerCase();
    if (!items.some((i) => i.id === id))
      items = [...items, { id, label: value }];
    selected = [...selected, id];
  }
</script>

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox
    {items}
    selectionMode="multiple"
    allowCreate
    aria-label="Labels"
    placeholder="Add or create a label…"
    bind:value={selected}
    {onCreate}
  />
  <p>Selected: {selected.join(", ") || "none"}</p>
</div>

Selected: none

<script setup lang="ts">
import { ref } from "vue";
import { Combobox } from "@pindoba/vue-combobox";
import type { Key, ComboboxValue } from "@pindoba/core-combobox";
import { stack } from "@pindoba/styled-system/patterns";

const items = ref([
  { id: "bug", label: "bug" },
  { id: "feature", label: "feature" },
  { id: "docs", label: "docs" },
]);
const selected = ref<Key[]>([]);

function onValueChange(value: ComboboxValue) {
  selected.value = (value as Key[]) ?? [];
}

function onCreate(value: string) {
  const id = value.toLowerCase();
  if (!items.value.some((i) => i.id === id))
    items.value = [...items.value, { id, label: value }];
  selected.value = [...selected.value, id];
}
</script>

<template>
  <div :class="stack({ gap: 'sm', alignItems: 'flex-start' })">
    <Combobox
      :items="items"
      selectionMode="multiple"
      allowCreate
      aria-label="Labels"
      placeholder="Add or create a label…"
      :value="selected"
      :onValueChange="onValueChange"
      :onCreate="onCreate"
    />
    <p>Selected: {{ selected.join(", ") || "none" }}</p>
  </div>
</template>

Leading content

Pass a leading snippet (Svelte) or leading slot (Astro) to render an icon inside the field — e.g. a search glyph.

AstroReactSvelteVue

PreviewCode

---
import Combobox from "../combobox.astro";
import { Search } from "@lucide/astro";
import Stamp from "@pindoba/astro-stamp";
import { stack } from "@pindoba/styled-system/patterns";

const items = [
  {
    id: "react",
    label: "React",
    description: "A library for web and native UIs",
  },
  {
    id: "svelte",
    label: "Svelte",
    description: "Cybernetically enhanced web apps",
  },
  { id: "vue", label: "Vue", description: "The progressive framework" },
  {
    id: "solid",
    label: "Solid",
    description: "Simple and performant reactivity",
  },
];
---

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox
    id="astro-cb-icons"
    items={items}
    aria-label="Framework"
    placeholder="Search…"
  >
    <Stamp emphasis="ghost" slot="leading"><Search /></Stamp>
  </Combobox>
</div>

import { Combobox } from "../Combobox";
import Stamp from "@pindoba/react-stamp";
import { stack } from "@pindoba/styled-system/patterns";
import React, { type JSX } from "react";

/** The search glyph (mirrors the Svelte demo's lucide Search icon). */
function Search({ size = 16 }: { size?: number }): JSX.Element {
  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width={size}
      height={size}
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      strokeWidth="2"
      strokeLinecap="round"
      strokeLinejoin="round"
      aria-hidden="true"
    >
      <circle cx="11" cy="11" r="8" />
      <path d="m21 21-4.3-4.3" />
    </svg>
  );
}

const items = [
  {
    id: "react",
    label: "React",
    description: "A library for web and native UIs",
  },
  {
    id: "svelte",
    label: "Svelte",
    description: "Cybernetically enhanced web apps",
  },
  { id: "vue", label: "Vue", description: "The progressive framework" },
  {
    id: "solid",
    label: "Solid",
    description: "Simple and performant reactivity",
  },
];

export default function WithIconsDemo() {
  return (
    <div className={stack({ gap: "sm", alignItems: "flex-start" })}>
      <Combobox
        items={items}
        aria-label="Framework"
        placeholder="Search…"
        leading={
          <Stamp emphasis="ghost">
            <Search size={16} />
          </Stamp>
        }
      />
    </div>
  );
}

<script lang="ts">
  import Combobox from "../combobox.svelte";
  import { stack } from "@pindoba/styled-system/patterns";
  import Stamp from "@pindoba/svelte-stamp";
  import Search from "@lucide/svelte/icons/search";

  const items = [
    {
      id: "react",
      label: "React",
      description: "A library for web and native UIs",
    },
    {
      id: "svelte",
      label: "Svelte",
      description: "Cybernetically enhanced web apps",
    },
    { id: "vue", label: "Vue", description: "The progressive framework" },
    {
      id: "solid",
      label: "Solid",
      description: "Simple and performant reactivity",
    },
  ];
</script>

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox {items} aria-label="Framework" placeholder="Search…">
    {#snippet leading()}
      <Stamp emphasis="ghost"><Search size={16} /></Stamp>
    {/snippet}
  </Combobox>
</div>

<script setup lang="ts">
import { Combobox } from "@pindoba/vue-combobox";
import { Stamp } from "@pindoba/vue-stamp";
import { stack } from "@pindoba/styled-system/patterns";
import { css } from "@pindoba/styled-system/css";
import { Search } from "./_icons";

const items = [
  {
    id: "react",
    label: "React",
    description: "A library for web and native UIs",
  },
  {
    id: "svelte",
    label: "Svelte",
    description: "Cybernetically enhanced web apps",
  },
  { id: "vue", label: "Vue", description: "The progressive framework" },
  {
    id: "solid",
    label: "Solid",
    description: "Simple and performant reactivity",
  },
];
</script>

<template>
  <div :class="stack({ gap: 'sm', alignItems: 'flex-start' })">
    <Combobox :items="items" aria-label="Framework" placeholder="Search…">
      <template #leading>
        <Stamp emphasis="ghost">
          <span :class="css({ '& svg': { width: '16px', height: '16px' } })">
            <Search />
          </span>
        </Stamp>
      </template>
    </Combobox>
  </div>
</template>

Sections

Group related options with section nodes (type: "section"). Filtering keeps section structure and hides any section that loses all its matches.

AstroReactSvelteVue

PreviewCode

---
import Combobox from "../combobox.astro";
import { stack } from "@pindoba/styled-system/patterns";
import type { ListBoxNodeInput } from "@pindoba/core-combobox";

const items: ListBoxNodeInput[] = [
  {
    id: "frontend",
    type: "section",
    title: "Frontend",
    items: [
      { id: "react", label: "React" },
      { id: "svelte", label: "Svelte" },
      { id: "vue", label: "Vue" },
    ],
  },
  {
    id: "backend",
    type: "section",
    title: "Backend",
    items: [
      { id: "node", label: "Node.js" },
      { id: "deno", label: "Deno" },
      { id: "bun", label: "Bun" },
    ],
  },
];
---

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox
    id="astro-cb-grouped"
    items={items}
    aria-label="Technology"
    placeholder="Search…"
  />
</div>

import { Combobox } from "../Combobox";
import { stack } from "@pindoba/styled-system/patterns";
import type { ListBoxNodeInput } from "@pindoba/core-combobox";
import React from "react";

const items: ListBoxNodeInput[] = [
  {
    id: "frontend",
    type: "section",
    title: "Frontend",
    items: [
      { id: "react", label: "React" },
      { id: "svelte", label: "Svelte" },
      { id: "vue", label: "Vue" },
    ],
  },
  {
    id: "backend",
    type: "section",
    title: "Backend",
    items: [
      { id: "node", label: "Node.js" },
      { id: "deno", label: "Deno" },
      { id: "bun", label: "Bun" },
    ],
  },
];

export default function GroupedDemo() {
  return (
    <div className={stack({ gap: "sm", alignItems: "flex-start" })}>
      <Combobox items={items} aria-label="Technology" placeholder="Search…" />
    </div>
  );
}

<script lang="ts">
  import Combobox from "../combobox.svelte";
  import { stack } from "@pindoba/styled-system/patterns";
  import type { ListBoxNodeInput } from "@pindoba/core-combobox";

  const items: ListBoxNodeInput[] = [
    {
      id: "frontend",
      type: "section",
      title: "Frontend",
      items: [
        { id: "react", label: "React" },
        { id: "svelte", label: "Svelte" },
        { id: "vue", label: "Vue" },
      ],
    },
    {
      id: "backend",
      type: "section",
      title: "Backend",
      items: [
        { id: "node", label: "Node.js" },
        { id: "deno", label: "Deno" },
        { id: "bun", label: "Bun" },
      ],
    },
  ];
</script>

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox {items} aria-label="Technology" placeholder="Search…" />
</div>

<script setup lang="ts">
import { Combobox } from "@pindoba/vue-combobox";
import type { ListBoxNodeInput } from "@pindoba/core-combobox";
import { stack } from "@pindoba/styled-system/patterns";

const items: ListBoxNodeInput[] = [
  {
    id: "frontend",
    type: "section",
    title: "Frontend",
    items: [
      { id: "react", label: "React" },
      { id: "svelte", label: "Svelte" },
      { id: "vue", label: "Vue" },
    ],
  },
  {
    id: "backend",
    type: "section",
    title: "Backend",
    items: [
      { id: "node", label: "Node.js" },
      { id: "deno", label: "Deno" },
      { id: "bun", label: "Bun" },
    ],
  },
];
</script>

<template>
  <div :class="stack({ gap: 'sm', alignItems: 'flex-start' })">
    <Combobox :items="items" aria-label="Technology" placeholder="Search…" />
  </div>
</template>

Async / remote data

Set filter={false} to turn off built-in filtering and feed your own results: handle onInputChange, fetch, and update items (toggle isLoading while in flight). The Svelte demo debounces a fake fetch; the Astro tab shows the loading state (true async needs a client island).

AstroReactSvelteVue

PreviewCode

---
import Combobox from "../combobox.astro";
import { stack } from "@pindoba/styled-system/patterns";

// Astro renders on the server, so this demo shows the loading state. True
// async (fetch-on-type with `filter={false}` + `onInputChange`) needs a
// client island — see the Svelte demo for the interactive version.
---

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox
    id="astro-cb-async"
    items={[]}
    isLoading
    aria-label="Fruit (async)"
    placeholder="Type to search…"
  />
</div>

import { Combobox } from "../Combobox";
import { stack } from "@pindoba/styled-system/patterns";
import type { ListBoxNodeInput } from "@pindoba/core-combobox";
import React, { useRef, useState } from "react";

const ALL = [
  "apple",
  "apricot",
  "banana",
  "blueberry",
  "cherry",
  "cranberry",
  "grape",
  "mango",
];

export default function AsyncDemo() {
  const [items, setItems] = useState<ListBoxNodeInput[]>([]);
  const [isLoading, setIsLoading] = useState(false);
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);

  // `filter={false}` disables built-in filtering — we fetch matches ourselves.
  function onInputChange(query: string) {
    clearTimeout(timer.current);
    if (query.trim() === "") {
      setItems([]);
      setIsLoading(false);
      return;
    }
    setIsLoading(true);
    timer.current = setTimeout(() => {
      const q = query.trim().toLowerCase();
      setItems(
        ALL.filter((f) => f.includes(q)).map((f) => ({ id: f, label: f })),
      );
      setIsLoading(false);
    }, 400);
  }

  return (
    <div className={stack({ gap: "sm", alignItems: "flex-start" })}>
      <Combobox
        items={items}
        isLoading={isLoading}
        filter={false}
        aria-label="Fruit (async)"
        placeholder="Type to search…"
        onInputChange={onInputChange}
      />
    </div>
  );
}

<script lang="ts">
  import Combobox from "../combobox.svelte";
  import { stack } from "@pindoba/styled-system/patterns";
  import type { ListBoxNodeInput } from "@pindoba/core-combobox";

  const ALL = [
    "apple",
    "apricot",
    "banana",
    "blueberry",
    "cherry",
    "cranberry",
    "grape",
    "mango",
  ];

  let items = $state<ListBoxNodeInput[]>([]);
  let isLoading = $state(false);
  let timer: ReturnType<typeof setTimeout> | undefined;

  // `filter={false}` disables built-in filtering — we fetch matches ourselves.
  function onInputChange(query: string) {
    clearTimeout(timer);
    if (query.trim() === "") {
      items = [];
      isLoading = false;
      return;
    }
    isLoading = true;
    timer = setTimeout(() => {
      const q = query.trim().toLowerCase();
      items = ALL.filter((f) => f.includes(q)).map((f) => ({
        id: f,
        label: f,
      }));
      isLoading = false;
    }, 400);
  }
</script>

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox
    {items}
    {isLoading}
    filter={false}
    aria-label="Fruit (async)"
    placeholder="Type to search…"
    {onInputChange}
  />
</div>

<script setup lang="ts">
import { ref } from "vue";
import { Combobox } from "@pindoba/vue-combobox";
import type { ListBoxNodeInput } from "@pindoba/core-combobox";
import { stack } from "@pindoba/styled-system/patterns";

const ALL = [
  "apple",
  "apricot",
  "banana",
  "blueberry",
  "cherry",
  "cranberry",
  "grape",
  "mango",
];

const items = ref<ListBoxNodeInput[]>([]);
const isLoading = ref(false);
let timer: ReturnType<typeof setTimeout> | undefined;

// `filter={false}` disables built-in filtering — we fetch matches ourselves.
function onInputChange(query: string) {
  clearTimeout(timer);
  if (query.trim() === "") {
    items.value = [];
    isLoading.value = false;
    return;
  }
  isLoading.value = true;
  timer = setTimeout(() => {
    const q = query.trim().toLowerCase();
    items.value = ALL.filter((f) => f.includes(q)).map((f) => ({
      id: f,
      label: f,
    }));
    isLoading.value = false;
  }, 400);
}
</script>

<template>
  <div :class="stack({ gap: 'sm', alignItems: 'flex-start' })">
    <Combobox
      :items="items"
      :isLoading="isLoading"
      :filter="false"
      aria-label="Fruit (async)"
      placeholder="Type to search…"
      :onInputChange="onInputChange"
    />
  </div>
</template>

Disabled options

Mark an option disabled, or list its key in disabledKeys. Disabled options are skipped by arrow navigation and can’t be selected.

AstroReactSvelteVue

PreviewCode

---
import Combobox from "../combobox.astro";
import { stack } from "@pindoba/styled-system/patterns";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue", disabled: true },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular", disabled: true },
];
---

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox
    id="astro-cb-disabled"
    items={items}
    aria-label="Framework"
    placeholder="Some options disabled…"
  />
</div>

import { Combobox } from "../Combobox";
import { stack } from "@pindoba/styled-system/patterns";
import React from "react";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue", disabled: true },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular", disabled: true },
];

export default function DisabledDemo() {
  return (
    <div className={stack({ gap: "sm", alignItems: "flex-start" })}>
      <Combobox
        items={items}
        aria-label="Framework"
        placeholder="Some options disabled…"
      />
    </div>
  );
}

<script lang="ts">
  import Combobox from "../combobox.svelte";
  import { stack } from "@pindoba/styled-system/patterns";

  const items = [
    { id: "react", label: "React" },
    { id: "svelte", label: "Svelte" },
    { id: "vue", label: "Vue", disabled: true },
    { id: "solid", label: "Solid" },
    { id: "angular", label: "Angular", disabled: true },
  ];
</script>

<div class={stack({ gap: "sm", alignItems: "flex-start" })}>
  <Combobox
    {items}
    aria-label="Framework"
    placeholder="Some options disabled…"
  />
</div>

<script setup lang="ts">
import { Combobox } from "@pindoba/vue-combobox";
import { stack } from "@pindoba/styled-system/patterns";

const items = [
  { id: "react", label: "React" },
  { id: "svelte", label: "Svelte" },
  { id: "vue", label: "Vue", disabled: true },
  { id: "solid", label: "Solid" },
  { id: "angular", label: "Angular", disabled: true },
];
</script>

<template>
  <div :class="stack({ gap: 'sm', alignItems: 'flex-start' })">
    <Combobox
      :items="items"
      aria-label="Framework"
      placeholder="Some options disabled…"
    />
  </div>
</template>

Keyboard

Focus stays on the input throughout.

Key	Action
Type	Filters the options and opens the popup
`↓` / `↑`	Open the popup, then move the active option
`Home` / `End`	Jump to the first / last option
`Enter`	Select the active option (or commit the “Create …” row)
`Escape`	Close the popup
`Backspace`	Remove the last chip when the query is empty (multiselect)
`Tab`	Move focus away and close the popup

Accessibility

The input is a role="combobox" with aria-expanded, aria-controls (the listbox id), aria-haspopup="listbox", and aria-autocomplete="list".
The consumer id lands on the inner <input>, so a plain <label for={id}> focuses the combobox (the input is natively labelable) — no Field wrapper required.
The active option is surfaced via aria-activedescendant; DOM focus never leaves the input.
The popup is a role="listbox" of role="option" rows with aria-selected.
The clear and chevron buttons are labelled and removed from the tab order (tabindex="-1"); chip remove buttons are labelled Remove <value>.

#Default

#Multiple selection

#Sizes

#Chip overflow

#Creatable

#Leading content

#Sections

#Async / remote data

#Disabled options

#Keyboard

#Accessibility

Default

Multiple selection

Sizes

Chip overflow

Creatable

Leading content

Sections

Async / remote data

Disabled options

Keyboard

Accessibility