Listbox

#Basic usage

Accent

listbox/basic.vue

<script setup lang="ts">
import { Listbox, createListCollection } from "@bysages/vue";

const pigments = createListCollection({
  items: [
    { label: "Qinghua cobalt", value: "qinghua" },
    { label: "Celadon", value: "celadon" },
    { label: "Zhusha cinnabar", value: "zhusha" },
    { label: "Ochre", value: "ochre" },
  ],
});
</script>

<template>
  <Listbox.Root :collection="pigments" selection-mode="single">
    <Listbox.Label>Accent</Listbox.Label>
    <Listbox.Content>
      <Listbox.Item v-for="item in pigments.items" :key="item.value" :item="item">
        <Listbox.ItemText>{{ item.label }}</Listbox.ItemText>
        <Listbox.ItemIndicator>
          <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
            <path
              d="M4 8.5l2.5 2.5L12 5.5"
              stroke="currentColor"
              stroke-width="1.5"
              stroke-linecap="round"
              stroke-linejoin="round"
            />
          </svg>
        </Listbox.ItemIndicator>
      </Listbox.Item>
    </Listbox.Content>
  </Listbox.Root>
</template>

#Props

#Content

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

Prop	Type	Default	Description
`autoHighlight`	`boolean \| undefined`	`false`	Whether to automatically highlight the item when typing
`keyboardPriority`	`"caret" \| "navigate" \| undefined`	`"caret"`	Determines how keyboard conflicts in the input are resolved. - "caret": keep native text-editing behavior - "navigate": forward supported keys to listbox navigation

#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
`highlightOnHover`	`boolean \| undefined`		Whether to highlight the item on hover
`item`	`T`		The item to render

#Label

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 ladder for the row register and the filter field.
`collection`	`ListCollection<T>`		The collection of items
`defaultHighlightedValue`	`string`		The initial value of the highlighted item when opened. Use when you don't need to control the highlighted value of the listbox.
`defaultValue`	`string[]`	`[]`	The initial default value of the listbox when rendered. Use when you don't need to control the value of the listbox.
`deselectable`	`boolean`		Whether to disallow empty selection
`disabled`	`boolean`		Whether the listbox is disabled
`disallowSelectAll`	`boolean`		Whether to disallow selecting all items when `meta+a` is pressed
`highlightedValue`	`string`		The controlled key of the highlighted item
`id`	`string`		The unique identifier of the machine.
`ids`	`Partial<{ root: string; content: string; label: string; item(id: string \| number): string; itemGroup(id: string \| number): string; itemGroupLabel(id: string \| number): string; }>`		The ids of the elements in the listbox. Useful for composition.
`loopFocus`	`boolean`	`false`	Whether to loop the keyboard navigation through the options
`modelValue`	`string[]`		The model value of the listbox
`orientation`	`'horizontal' \| 'vertical'`	`"horizontal"`	The orientation of the element.
`scrollToIndexFn`	`(details: listbox.ScrollToIndexDetails) => void`		Function to scroll to a specific index
`selectionMode`	`listbox.SelectionMode`	`"single"`	How multiple selection should behave in the listbox. - `single`: The user can select a single item. - `multiple`: The user can select multiple items without using modifier keys. - `extended`: The user can select multiple items by using modifier keys.
`selectOnHighlight`	`boolean`		Whether to select the item when it is highlighted
`typeahead`	`boolean`		Whether to enable typeahead on the listbox

#ValueText

Prop	Type	Default	Description
`placeholder`	`string`		—