Listbox

Move through a visible option list and select one or several values.

Usage

Single

Keep one active value while moving and selecting with keyboard or pointer input.

<!-- Listbox / Single -->
<script setup lang="ts">
import { ListboxItem, ListboxItemIndicator, ListboxItemText, ListboxRoot } from '@sectile/vue/listbox'

const items = ['production', 'staging', 'development']
</script>

<template>
  <ListboxRoot
    :items="items"
    selection-mode="single"
    :default-value="'production'"
  >
    <ListboxItem v-for="item in items" :key="item" :value="item">
      <ListboxItemText>{{ item }}</ListboxItemText>
      <ListboxItemIndicator>Selected</ListboxItemIndicator>
    </ListboxItem>
  </ListboxRoot>
</template>

Multiple

Select several values independently without collapsing the existing selection.

<!-- Listbox / Multiple -->
<script setup lang="ts">
import { ListboxItem, ListboxItemIndicator, ListboxItemText, ListboxRoot } from '@sectile/vue/listbox'

const items = ['production', 'staging', 'development']
</script>

<template>
  <ListboxRoot
    :items="items"
    selection-mode="multiple"
    :default-value="['production', 'development']"
  >
    <ListboxItem v-for="item in items" :key="item" :value="item">
      <ListboxItemText>{{ item }}</ListboxItemText>
      <ListboxItemIndicator>Selected</ListboxItemIndicator>
    </ListboxItem>
  </ListboxRoot>
</template>

Follow focus

Move selection together with the active listbox item.

<!-- Listbox / Follow Focus -->
<script setup lang="ts">
import { ListboxItem, ListboxItemIndicator, ListboxItemText, ListboxRoot } from '@sectile/vue/listbox'

const items = ['production', 'staging', 'development']
</script>

<template>
  <ListboxRoot
    :items="items"
    selection-mode="single"
    :default-value="'production'"
  >
    <ListboxItem v-for="item in items" :key="item" :value="item">
      <ListboxItemText>{{ item }}</ListboxItemText>
      <ListboxItemIndicator>Selected</ListboxItemIndicator>
    </ListboxItem>
  </ListboxRoot>
</template>

Controlled

Let the parent own the current value and apply accepted changes back to the component.

<!-- Listbox / Controlled -->
<script setup lang="ts">
import { ListboxItem, ListboxItemIndicator, ListboxItemText, ListboxRoot } from '@sectile/vue/listbox'

const items = ['production', 'staging', 'development']
</script>

<template>
  <ListboxRoot
    :items="items"
    selection-mode="single"
    :default-value="'production'"
  >
    <ListboxItem v-for="item in items" :key="item" :value="item">
      <ListboxItemText>{{ item }}</ListboxItemText>
      <ListboxItemIndicator>Selected</ListboxItemIndicator>
    </ListboxItem>
  </ListboxRoot>
</template>

API

Vue package: @sectile/vue/listbox

Components

ListboxRoot
ListboxItem
ListboxItemText
ListboxItemIndicator

Props

`ListboxRootProps`

as: TypePrimitiveAsDefault'div'
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.
defaultValue: TypeListboxValueDefaultundefined
Initial value used when the component owns its state.
disabled: TypebooleanDefaultfalse
Whether interaction is unavailable.
disabledItems: Typereadonly string[]Default[]
Item values excluded from focus and selection.
form: TypestringDefaultundefined
ID of the native form associated with the control.
items: Typereadonly string[]DefaultRequired
Ordered item values managed by the component.
modelValue: TypeListboxValueDefaultundefined
Current value when state is controlled by the parent.
name: TypestringDefaultundefined
Name used for native form submission.
orientation: Type'horizontal' | 'vertical'Default'vertical'
Axis used for layout and keyboard movement.
readonly: TypebooleanDefaultfalse
Whether the value can be inspected but not changed.
required: TypebooleanDefaultfalse
Whether the control must contain a valid value before submission.
selectionMode: TypeListboxSelectionModeDefault'single'
Whether selection contains one value or multiple values.
textValue: Type(id: string) => stringDefaultundefined
Returns searchable or presentational text for an item value.

`ListboxItemProps`

as: TypePrimitiveAsDefault'div'
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.
disabled: TypebooleanDefaultfalse
Whether interaction is unavailable.
value: TypestringDefaultRequired
Current value exposed by this contract.

`ListboxPartProps`

as: TypePrimitiveAsDefaultVaries by part
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.

Slots

`ListboxRootSlotProps`

disabled: Typeboolean
Whether interaction is unavailable.
highlightedValue: Typestring | null
Value currently highlighted for interaction.
readonly: Typeboolean
Whether the value can be inspected but not changed.
value: TypeListboxValue
Current value exposed by this contract.

`ListboxItemSlotProps`

disabled: Typeboolean
Whether interaction is unavailable.
highlighted: Typeboolean
Whether this item is highlighted for interaction.
selected: Typeboolean
Whether this item is selected.
value: Typestring
Current value exposed by this contract.

Events

`ListboxRoot`

activate: Payloadstring
Emitted when an item becomes active.
highlight: Payloadstring | null
Emitted when the highlighted item changes.
update:modelValue: PayloadListboxValue
Emitted when the component requests a new controlled value.

Other types

`ListboxSelectionMode`

type ListboxSelectionMode = 'single' | 'multiple'

`ListboxValue`

type ListboxValue = string | readonly string[]

`ListboxTextValueResolver`

type ListboxTextValueResolver = NonNullable<ListboxRootProps['textValue']>

`ListboxValueChangeHandler`

type ListboxValueChangeHandler = (value: ListboxValue) => void

`ListboxHighlightHandler`

type ListboxHighlightHandler = (value: string | null) => void

`ListboxActivateHandler`

type ListboxActivateHandler = (value: string) => void

Parts

Shared scope: [data-scope="listbox"]. Combine it with a part selector to keep styles local to this component.

Part	Selector	Role	Extra attributes
`root`	`[data-part="root"]`	Defines the component boundary and owns its composed parts.	—
`item`	`[data-part="item"]`	Represents one selectable or actionable item.	—
`item-text`	`[data-part="item-text"]`	Renders the item label independently from its controls.	—
`item-indicator`	`[data-part="item-indicator"]`	Shows the item selection state.	—

Keyboard interaction

Key	Behavior
`Arrow keys`	Move the active option in the visible orientation.
`Home` / `End`	Move to the first or last eligible option.
`Enter` / `Space`	Select or activate the current option.
`Printable text`	Move to the next matching option when typeahead is available.

Accessibility

The labeled listbox exposes active, selected, and disabled option state without moving DOM focus to every item.

See the corresponding WAI-ARIA pattern for the host accessibility contract.

Listbox ​

Usage ​

Single ​

Multiple ​

Follow focus ​

Controlled ​

API ​

Props ​

ListboxRootProps ​

ListboxItemProps ​

ListboxPartProps ​

Slots ​

ListboxRootSlotProps ​

ListboxItemSlotProps ​

Events ​

ListboxRoot ​

Other types ​

ListboxSelectionMode ​

ListboxValue ​

ListboxTextValueResolver ​

ListboxValueChangeHandler ​

ListboxHighlightHandler ​

ListboxActivateHandler ​

Parts ​

Keyboard interaction ​

Accessibility ​