Kappa / Combobox

<script setup>
import { ref } from "vue";
import { Combobox } from "@dicehub/kappa/components/combobox";

const value = ref(["eu-central"]);
const regions = [
  { label: "EU Central · Frankfurt", value: "eu-central" },
  { label: "EU West · Dublin", value: "eu-west" },
  { label: "US East · Virginia", value: "us-east" },
];
</script>

<template>
  <Combobox
    v-model="value"
    :items="regions"
    label="Compute region"
    description="Routes the run to the selected cluster."
    input-behavior="autohighlight"
    placeholder="Select a region"
  />
</template>

Installation

Combobox is part of the main Kappa package. Ark UI owns focus, keyboard navigation, selection, form values, live option state, and floating positioning.

Barrel

import {
  Combobox,
  createComboboxCollection,
} from "@dicehub/kappa";

Granular

import {
  Combobox,
  createComboboxCollection,
} from "@dicehub/kappa/components/combobox";

Usage

Use Combobox when the submitted value must come from a known collection. It rejects custom text by default. Use Autocomplete when free-form text is valid.

<script setup>
import { ref } from "vue";
import {
  Combobox,
  createComboboxCollection,
} from "@dicehub/kappa/components/combobox";

const value = ref(["openfoam"]);
const collection = createComboboxCollection({
  items: [
    { label: "Binary mesh", value: "binary" },
    { label: "OpenFOAM mesh", value: "openfoam" },
  ],
  itemToString: (item) => item.label,
  itemToValue: (item) => item.value,
});
</script>

<template>
  <Combobox v-model="value" :collection="collection" label="Mesh format">
    <Combobox.TriggerInput placeholder="Select a format" />
    <Combobox.Content>
      <Combobox.Empty>No matching format.</Combobox.Empty>
      <Combobox.List>
        <template #default="{ item }">
          <Combobox.Item :item="item">{{ item.label }}</Combobox.Item>
        </template>
      </Combobox.List>
    </Combobox.Content>
  </Combobox>
</template>

Composition

Typical part hierarchy

Combobox.Root
├── Combobox.Label
├── Combobox.TriggerInput / TriggerValue / TriggerMultipleWithInput
└── Combobox.Content
    ├── Combobox.Input (optional popup search)
    ├── Combobox.Empty
    └── Combobox.List
        ├── Combobox.Group
        │   ├── Combobox.GroupLabel
        │   └── Combobox.Item
        │       ├── Combobox.ItemText
        │       └── Combobox.ItemIndicator
        └── Combobox.Separator

TriggerInput is an editable control. TriggerValue is a select-like button. Add Input inside Content when a button trigger still needs search. Multiple selection uses TriggerMultipleWithInput.

Content teleports to body by default and accepts Ark positioning props such as placement, sameWidth, flip, andstrategy.

Examples

Keep the selected value quiet until the user opens a searchable popup.

<Combobox v-model="language" :collection="languages">
  <Combobox.TriggerValue placeholder="Select a language" />
  <Combobox.Content>
    <Combobox.Input aria-label="Search languages" placeholder="Search languages" />
    <Combobox.Empty>No matching language.</Combobox.Empty>
    <Combobox.List>
      <template #default="{ item }">
        <Combobox.Item :item="item">{{ item.label }}</Combobox.Item>
      </template>
    </Combobox.List>
  </Combobox.Content>
</Combobox>

Custom Trigger

Use asChild to merge Ark trigger behavior into one Kappa Button.

<script setup>
import { Button } from "@dicehub/kappa/components/button";
import { Combobox } from "@dicehub/kappa/components/combobox";
</script>

<template>
  <Combobox v-model="language" :collection="languages">
    <Combobox.Trigger as-child>
      <Button variant="outline">
        Language: <Combobox.Value />
      </Button>
    </Combobox.Trigger>
    <Combobox.Content :same-width="false">
      <Combobox.List>
        <template #default="{ item }">
          <Combobox.Item :item="item">{{ item.label }}</Combobox.Item>
        </template>
      </Combobox.List>
    </Combobox.Content>
  </Combobox>
</template>

Grouped Options

The root scoped slot exposes the filtered collection, so empty groups disappear with the query.

<script setup>
import { Combobox, createComboboxCollection } from "@dicehub/kappa/components/combobox";

const collection = createComboboxCollection({
  items: solvers,
  groupBy: (item) => item.group,
  itemToString: (item) => item.label,
  itemToValue: (item) => item.value,
});
</script>

<template>
  <Combobox v-model="solver" :collection="collection">
    <template #default="{ collection: filteredCollection }">
      <Combobox.TriggerInput placeholder="Select a solver" />
      <Combobox.Content>
        <Combobox.Empty>No matching solver.</Combobox.Empty>
        <Combobox.List :render-items="false">
          <Combobox.Group
            v-for="[group, items] in filteredCollection.group()"
            :key="group"
          >
            <Combobox.GroupLabel>{{ group }}</Combobox.GroupLabel>
            <Combobox.Item v-for="item in items" :key="item.value" :item="item">
              {{ item.label }}
            </Combobox.Item>
          </Combobox.Group>
        </Combobox.List>
      </Combobox.Content>
    </template>
  </Combobox>
</template>

Multiple Values

Selected values become removable chips. The popup stays open after each selection.

<Combobox v-model="tags" :collection="tagCollection" multiple>
  <Combobox.TriggerMultipleWithInput placeholder="Add a tag" />
  <Combobox.Content>
    <Combobox.Empty>No matching tag.</Combobox.Empty>
    <Combobox.List>
      <template #default="{ item }">
        <Combobox.Item :item="item">{{ item.label }}</Combobox.Item>
      </template>
    </Combobox.List>
  </Combobox.Content>
</Combobox>

Sizes

<Combobox size="xs" :items="regions" aria-label="Extra small region" />
<Combobox size="sm" :items="regions" aria-label="Small region" />
<Combobox size="base" :items="regions" aria-label="Base region" />
<Combobox size="lg" :items="regions" aria-label="Large region" />

Disabled and Invalid

Error text sets invalid state and joins the input's accessible description.

<Combobox
  :items="formats"
  disabled
  label="Source format"
  placeholder="Unavailable"
/>

<Combobox
  v-model="format"
  :items="formats"
  error="Select one supported output format."
  label="Output format"
  placeholder="Required"
  required
/>

Accessibility

Arrow Down and Arrow Up move through enabled options.
Enter selects the highlighted option. Escape closes the popup.
Home and End move to the first and last enabled options.
Labels, descriptions, errors, disabled state, and invalid state stay connected.
Selected indicators are visual support; Ark announces selection state.
Popup motion honors prefers-reduced-motion.

Kappa preserves the primitive contract. See theofficial Ark UI Combobox documentation.

API Reference

Combobox.Root

Forwards remaining attributes, listeners, controlled state, and Ark UI root behavior.

Prop	Type	Default	Description
`items`	`readonly T[]`	`[]`	Items for the convenience composition.
`collection`	`ComboboxCollection<T>`	`generated`	Ark list collection for mapped items, groups, and disabled state.
`modelValue`	`string[]`	`-`	Controlled selection; supports v-model.
`defaultValue`	`string[]`	`[]`	Initial uncontrolled selection.
`inputValue`	`string`	`-`	Controlled text; supports v-model:input-value.
`open`	`boolean`	`-`	Controlled popup state; supports v-model:open.
`multiple`	`boolean`	`false`	Allows more than one selected value.
`allowCustomValue`	`boolean`	`false`	Allows text that is not a collection item when true.
`filter`	`false \| (item, query) => boolean`	`contains label`	Local filter. Pass false for external filtering.
`itemToString`	`(item) => string`	`item.label`	Maps an item to visible and searchable text.
`itemToValue`	`(item) => string`	`item.value`	Maps an item to its stable value.
`isItemDisabled`	`(item) => boolean`	`item.disabled`	Marks options unavailable and removes them from keyboard selection.
`showOnEmpty`	`boolean`	`true`	Shows all items before a query is entered.
`closeOnSelect`	`boolean`	`!multiple`	Closes after selection for single-value use.
`selectionBehavior`	`"clear" \| "replace" \| "preserve"`	`clear for multiple; replace otherwise`	Controls input text after selection.
`size`	`"xs" \| "sm" \| "base" \| "lg"`	`"base"`	Control height and text density.
`disabled / readOnly / invalid / required`	`boolean`	`false`	Field interaction and validation states.
`label / description / error`	`string`	`-`	Connected field copy for the convenience composition.
`positioning`	`ComboboxPositioningOptions`	`viewport-safe bottom-start`	Ark floating position options.
`lazyMount / unmountOnExit`	`boolean`	`false`	Popup render strategy.

Parts

Part	Element	Description
`Combobox.TriggerInput`	`input control`	Editable trigger with optional clear and toggle buttons.
`Combobox.TriggerValue`	`button`	Select-like trigger that displays the current value.
`Combobox.TriggerMultipleWithInput`	`input control`	Chip list and filter input for multiple selection.
`Combobox.Content`	`div`	Portalled popup. It also accepts every Ark positioning option.
`Combobox.Input`	`input`	Ark-connected input for custom controls or popup search.
`Combobox.List`	`div`	Scrollable listbox with scoped item rendering.
`Combobox.Item`	`div`	Selectable option with text and selected indicator parts.
`Combobox.Group / GroupLabel`	`div`	Accessible grouped-option structure.
`Combobox.Chip`	`span`	Selected value with an accessible remove button.
`Combobox.Trigger / Value`	`button / span`	Low-level parts for a custom select-like trigger.
`Combobox.Control / ClearTrigger`	`div / button`	Low-level editable-control composition.
`Combobox.Empty / Separator / Context`	`various`	Empty, visual grouping, and reactive state helpers.

Events

Event	Payload	Description
`update:modelValue`	`string[]`	Updates v-model after selection changes.
`valueChange`	`ComboboxValueChangeDetails<T>`	Provides selected values and items.
`update:inputValue`	`string`	Updates v-model:input-value after text changes.
`inputValueChange`	`ComboboxInputValueChangeDetails`	Provides text and the Ark change reason.
`update:open`	`boolean`	Updates v-model:open.
`openChange`	`ComboboxOpenChangeDetails`	Provides the new popup state and reason.
`highlightChange / select`	`Ark details`	Reports active-option and selection interactions.

Exports

Export	Description
`Combobox`	Compound component with every Kappa part attached.
`ComboboxRoot`	Unaugmented root component.
`Combobox* parts`	Named exports for all controls, triggers, popup, list, item, group, chip, and context parts.
`createComboboxCollection`	Kappa alias for Ark createListCollection.
`useComboboxCollection`	Reactive collection helper.
`useCombobox / useComboboxContext / useComboboxItemContext`	Ark state and context hooks.
`comboboxAnatomy`	Ark part anatomy metadata.
`COMBOBOX_SIZES`	Readonly list of supported sizes.
`Combobox* types`	Root, part, event, collection, filter, item, and positioning contracts.