Combobox

#Basic usage

Fruit

combobox/basic.vue

<script setup lang="ts">
import { useListCollection } from "@ark-ui/vue/combobox";
import { useFilter } from "@ark-ui/vue/locale";
import { check, chevron_down, x } from "@bysages/icons";
import { Combobox, Icon } from "@bysages/vue";

const filters = useFilter({ sensitivity: "base" });
const { collection, filter } = useListCollection({
  initialItems: [
    { label: "Apple", value: "apple" },
    { label: "Banana", value: "banana" },
    { label: "Cherry", value: "cherry" },
    { label: "Date", value: "date" },
    { label: "Elderberry", value: "elderberry" },
    { label: "Fig", value: "fig" },
  ],
  filter: (item: string, inputValue: string) => filters.value.contains(item, inputValue),
});
</script>

<template>
  <Combobox.Root :collection="collection" @input-value-change="(e) => filter(e.inputValue)">
    <Combobox.Label>Fruit</Combobox.Label>
    <Combobox.Control>
      <Combobox.Input placeholder="e.g. Apple" />
      <Combobox.ClearTrigger>
        <Icon :glyph="x" />
      </Combobox.ClearTrigger>
      <Combobox.Trigger>
        <Icon :glyph="chevron_down" />
      </Combobox.Trigger>
    </Combobox.Control>
    <Teleport to="body">
      <Combobox.Positioner>
        <Combobox.Content>
          <Combobox.Empty>No results found</Combobox.Empty>
          <Combobox.Item v-for="item in collection.items" :key="item.value" :item="item">
            <Combobox.ItemText>{{ item.label }}</Combobox.ItemText>
            <Combobox.ItemIndicator>
              <Icon :glyph="check" />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        </Combobox.Content>
      </Combobox.Positioner>
    </Teleport>
  </Combobox.Root>
</template>

#Props

#ClearTrigger

A styled part — no props of its own; it takes the anatomy's shared styling.

#Content

A styled part — no props of its own; it takes the anatomy's shared styling.

#Control

A styled part — no props of its own; it takes the anatomy's shared styling.

#Empty

A styled part — no props of its own; it takes the anatomy's shared styling.

#Input

A styled part — no props of its own; it takes the anatomy's shared styling.

#ItemContext

A styled part — no props of its own; it takes the anatomy's shared styling.

#ItemGroupLabel

A styled part — no props of its own; it takes the anatomy's shared styling.

#ItemGroup

A styled part — no props of its own; it takes the anatomy's shared styling.

#ItemIndicator

A styled part — no props of its own; it takes the anatomy's shared styling.

#ItemText

A styled part — no props of its own; it takes the anatomy's shared styling.

#Item

Prop	Type	Default	Description
`item`	`CollectionItem`		The item to render
`persistFocus`	`boolean \| undefined`		Whether hovering outside should clear the highlighted state

#Label

A styled part — no props of its own; it takes the anatomy's shared styling.

#List

A styled part — no props of its own; it takes the anatomy's shared styling.

#Positioner

A styled part — no props of its own; it takes the anatomy's shared styling.

#Root

Prop	Type	Default	Description
`size`	`String as PropType<"sm" \| "md" \| "lg">`	`"md"`	One rung of the control-height ladder for the field row.
`allowCustomValue`	`boolean`		Whether to allow typing custom values in the input
`alwaysSubmitOnEnter`	`boolean`		Whether to allow bypassing the default two-step behavior (Enter to close combobox, then Enter to submit form) and instead submit the form immediately on Enter press. This is useful for single-field autocomplete forms where Enter should submit the form directly.
`autoFocus`	`boolean`		Whether to autofocus the input on mount
`closeOnSelect`	`boolean`		Whether to close the combobox when an item is selected.
`collection`	`ListCollection<T>`		The collection of items
`composite`	`boolean`	`true`	Whether the combobox is a composed with other composite widgets like tabs
`defaultHighlightedValue`	`string`		The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox.
`defaultInputValue`	`string`	`""`	The initial value of the combobox's input when rendered. Use when you don't need to control the value of the combobox's input.
`defaultOpen`	`boolean`		The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox.
`defaultValue`	`string[]`	`[]`	The initial value of the combobox's selected items when rendered. Use when you don't need to control the value of the combobox's selected items.
`disabled`	`boolean`		Whether the combobox is disabled
`disableLayer`	`boolean`		Whether to disable registering this a dismissable layer
`form`	`string`		The associate form of the combobox.
`highlightedValue`	`string`		The controlled highlighted value of the combobox
`id`	`string`		The unique identifier of the machine.
`ids`	`Partial<{ root: string; label: string; control: string; input: string; content: string; trigger: string; clearTrigger: string; item(id: string, index?: number): string; positioner: string; itemGroup(id: string \| number): string; itemGroupLabel(id: string \| number): string; }>`		The ids of the elements in the combobox. Useful for composition.
`inputBehavior`	`'autohighlight' \| 'autocomplete' \| 'none'`	`"none"`	Defines the auto-completion behavior of the combobox. - `autohighlight`: The first focused item is highlighted as the user types - `autocomplete`: Navigating the listbox with the arrow keys selects the item and the input is updated
`inputValue`	`string`		The controlled value of the combobox's input
`invalid`	`boolean`		Whether the combobox is invalid
`loopFocus`	`boolean`	`true`	Whether to loop the keyboard navigation through the items
`modelValue`	`string[]`		The v-model value of the combobox
`multiple`	`boolean`		Whether to allow multiple selection. Good to know: When `multiple` is `true`, the `selectionBehavior` is automatically set to `clear`. It is recommended to render the selected items in a separate container.
`name`	`string`		The `name` attribute of the combobox's input. Useful for form submission
`navigate`	`(details: combobox.NavigateDetails) => void`		Function to navigate to the selected item
`open`	`boolean`		The controlled open state of the combobox
`openOnChange`	`boolean \| ((details: combobox.InputValueChangeDetails) => boolean)`	`true`	Whether to show the combobox when the input value changes
`openOnClick`	`boolean`	`false`	Whether to open the combobox popup on initial click on the input
`openOnKeyPress`	`boolean`	`true`	Whether to open the combobox on arrow key press
`placeholder`	`string`		The placeholder text of the combobox's input
`positioning`	`combobox.PositioningOptions`	`{ placement: "bottom-start" }`	The positioning options to dynamically position the menu
`readOnly`	`boolean`		Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it
`required`	`boolean`		Whether the combobox is required
`scrollToIndexFn`	`(details: combobox.ScrollToIndexDetails) => void`		Function to scroll to a specific index
`selectionBehavior`	`'clear' \| 'replace' \| 'preserve'`	`"replace"`	The behavior of the combobox input when an item is selected - `replace`: The selected item string is set as the input value - `clear`: The input value is cleared - `preserve`: The input value is preserved
`translations`	`combobox.IntlTranslations`		Specifies the localized strings that identifies the accessibility elements and their states

#Trigger

Prop	Type	Default	Description
`focusable`	`boolean \| undefined`		Whether the trigger is focusable