Listbox

SListbox is an always-visible list of options: what a select shows inside its dropdown, usable on its own. It fits a picker in a settings panel, a command list, a filter column next to a table — any place where the choices should stay on screen instead of hiding behind a trigger.

Use SSelect when the value belongs in a form field: it has a labelled frame, a placeholder, a floating label and validation. SListbox is the bare surface — no frame chrome, no trigger — so it also composes inside popovers, drawers and command palettes.

Options come from the options array, the value is bound with v-model: a single value by default, an array of them with multiple.

Reka UI owns the interaction. Tab moves onto the list (focus lands on the active option, not on the whole list), the arrow keys and Home/End move between options and skip the disabled ones, typing the first letters of a label jumps to it, and Space or Enter picks the highlighted option. The list reports itself as role="listbox" with role="option" rows, so it needs an accessible name: pass label, or point your own aria-labelledby at a visible heading.

Single selection

<script setup lang="ts">
import { ref } from 'vue'

const city = ref('nyc')
const cities = [
  { label: 'New York', value: 'nyc' },
  { label: 'Los Angeles', value: 'la' },
  { label: 'Chicago', value: 'chi' },
  { label: 'Houston', value: 'hou', disabled: true },
]
</script>

<template>
  <SListbox
    v-model="city"
    label="City"
    :options="cities"
  />
</template>

Picking the selected option clears it, the way a checkbox does. Set selection-behavior="replace" to keep exactly one option picked at all times. With multiple, replace also gives the keyboard a range: Shift with the arrow keys, Home or End extends the selection from the last pick. The range is a keyboard gesture — Shift with a click is an ordinary click.

Multiple selection

With multiple the model becomes an array, every pick toggles its own option, and the list announces itself as multi-selectable.

<script setup lang="ts">
import { ref } from 'vue'

const visited = ref(['nyc', 'chi'])
</script>

<template>
  <SListbox
    v-model="visited"
    multiple
    label="Visited cities"
    :options="cities"
  />
</template>

Option content

An option takes an icon — a name from the icon registry or a raw path. For anything richer, the option slot replaces the whole row and receives the option itself along with its selected and disabled state.

<template>
  <SListbox
    v-model="view"
    label="View"
    :options="[
      { label: 'Overview', value: 'overview', icon: 'home' },
      { label: 'Documents', value: 'docs', icon: 'file-text' },
    ]"
  />

  <SListbox
    v-model="member"
    label="Member"
    :options="members"
  >
    <template #option="{ option, selected }">
      <span style="flex: 1">{{ option.label }}</span>
      <SBadge
        :variant="selected ? 'primary' : 'neutral'"
        size="sm"
      >
        {{ option.role }}
      </SBadge>
    </template>
  </SListbox>
</template>

Long lists (max-height)

max-height is the height the list may grow to before it starts scrolling; a number means pixels. The list scrolls inside a scroll area, and moving the highlight with the keyboard keeps the active option in view.

<template>
  <SListbox
    v-model="release"
    label="Release"
    :options="releases"
    :max-height="220"
  />
</template>

Empty state

With an empty options array the list shows a message from the locale dictionary — the listboxEmpty key, "No options". Override it with empty-text, or replace it entirely with the empty slot.

<template>
  <SListbox
    label="Members"
    :options="[]"
    empty-text="Nobody has joined yet"
  />

  <SListbox
    label="Members"
    :options="[]"
  >
    <template #empty>
      <SButton
        variant="ghost"
        size="sm"
      >
        Invite a teammate
      </SButton>
    </template>
  </SListbox>
</template>

Sizes and shape

size sets the option row height — sm (32px), md (40px) or lg (48px) — and square removes the rounding of the frame.

<template>
  <SListbox
    label="Small"
    size="sm"
    :options="views"
  />

  <SListbox
    label="Large"
    size="lg"
    square
    :options="views"
  />
</template>

API

Props

Name	Type	Default	Description
options*	{ label: string; value: string; disabled?: boolean; icon?: string }[]	required	List of options.
size	"md" | "sm" | "lg"	"md"	Option row size: sm (32px), md (40px), or lg (48px).
multiple	boolean	false	Multiple selection. modelValue becomes string[], and the list reports itself as multi-selectable to assistive technology.
selection-behavior	"replace" | "toggle"	"toggle"	How picking an option changes the selection. toggle (the default) flips the option: picking a selected one clears it, which is how checkbox-like lists behave. replace keeps exactly one pick per action — a click always wins over the previous selection, and with multiple Shift with the arrow keys, Home or End extends the range from the last pick. The range is a keyboard gesture only: a Shift-click is an ordinary click.
label	string	undefined	Accessible name of the list. A listbox has no visible label of its own, so either set this or point aria-labelledby at your own heading.
empty-text	string	undefined	Text shown when options is empty (taken from the locale dictionary by default).
max-height	string | number	undefined	Height the list is allowed to grow to before it starts scrolling; a number means pixels. Without it the list is as tall as its options.
square	boolean	false	Square corners: removes the list border rounding (rounded by default).
disabled	boolean	false	Disables the whole list: no option can be picked or focused.
model-value	string | string[]	undefined	Selection: the option value (string), or an array of them with multiple (string[]). Two-way binding via v-model.

Events

Name	Signature	Description
update:modelValue	( value: | string | string[] | undefined ) => void	Emitted when modelValue changes. Used for two-way binding (v-model).

Slots

Name	Description
option	Option row: replaces the icon, the label and the selected indicator.
empty	Message shown when there are no options.