Listbox

updated

No dropdown. No surprises. A list to pick one or more options from, with icons, titles and descriptions.

Demo
Nuxt
Vite
Astro
Laravel
Remix

Open Props in the corner of the example to try variant, size and disabled. Options are 28, 32, 36, 40 and 48px tall from xs to xl, as tall as a menu item or an input of the same size, and their text, icons, padding and gaps grow with them on the control scale. A disabled option cannot be selected, and the arrow keys skip it; a disabled listbox dims every option and ignores the pointer and the keyboard.

Installation

Usage

<script setup lang="ts">
import {
  Listbox,
  ListboxContent,
  ListboxDescription,
  ListboxIcon,
  ListboxItem,
  ListboxTitle,
} from '@/components/ui/listbox'

const channel = ref('email')
</script>

<template>
  <Listbox v-model="channel" aria-label="Notify me by">
    <ListboxItem value="email">
      <ListboxIcon><MailIcon /></ListboxIcon>
      <ListboxContent>
        <ListboxTitle>Email</ListboxTitle>
        <ListboxDescription>A daily digest at 9:00.</ListboxDescription>
      </ListboxContent>
    </ListboxItem>
  </Listbox>
</template>
  • ListboxItem: one option; a selected one gets a tint and a check
  • ListboxIcon: an icon at the start
  • ListboxContent: holds ListboxTitle and ListboxDescription, or just put text in the item

Start typing, and the list jumps to the matching option.

Width classes and aria-label go straight on Listbox. Or put it in a Field.

Examples

Icons, titles and descriptions

ListboxIcon holds an icon at the start of the option. It is hidden from screen readers and turns --primary with the option. Icons are 16px unless they set their own size. Below they are 20px, which suits two lines of text.

Icons
Email
A daily digest at 9:00.
Push
Right away, on every device.
SMS
Only for security alerts.

Custom indicator

Replace the check in the indicator-icon slot. Here selection-behavior="replace" also keeps one plan chosen at all times: by default, clicking the selected option clears it.

Indicator
Hobby
1 project, community support
Pro
Unlimited projects, email support
Team
Shared workspaces and SSO

Multiple

With multiple, v-model is an array and each click adds or removes an option. Screen readers announce the listbox as multi-select.

Multiple
Mozzarella
Basil
Mushrooms
Olives
Pepperoni
Jalapeños

2 of 6 chosen

Groups

ListboxGroup gathers options under a ListboxGroupLabel, which also names the group for screen readers. ListboxSeparator draws a line between groups and is hidden from screen readers.

Groups
Europe
London
Berlin
Helsinki
Americas
New York
Chicago
São Paulo

On select

ListboxItem fires select when it is clicked or chosen with the keyboard, with the value in event.detail.value. Call event.preventDefault() to run an action without selecting the option, which turns the listbox into a list of commands.

Select
roadmap.md
Edited 2 minutes ago
invoice-0142.pdf
Edited yesterday
brand-colors.json
Edited last week

Nothing opened yet

In a scroll area

Long list? Put a variant="ghost" listbox in a ScrollArea and move the border to the scroll area. Arrow keys keep the highlighted option in view.

In a scroll area
Arabic
Bengali
Chinese
Czech
Danish
Dutch
English
Finnish
French
German
Greek
Hebrew
Hindi
Hungarian
Indonesian
Italian
Japanese
Korean
Norwegian
Polish
Portuguese
Russian
Spanish
Swedish
Turkish
Ukrainian
Vietnamese

Field

In a required field the listbox gets aria-required, and when the field is invalid, aria-invalid and a --destructive frame. Press Continue without choosing a region.

Field
Frankfurt
Helsinki
Virginia
Oregon
Singapore

Where your data is stored. Click the chosen region again to clear it.

API Reference

Every part accepts class, merged over its base classes.

Data attributes

data-slotAttributesDescription
listboxdata-variant, data-size, data-orientation, data-disabledThe element with role="listbox". Receives class and attributes.
listbox-root—Reka UI's root, laid out with display: contents.
listbox-itemdata-state, data-highlighted, data-disabledOne option. data-state is checked or unchecked; data-highlighted marks the option the keyboard is on.
listbox-item-indicator—The check at the end of a selected option.
listbox-icon—The icon at the start of an option.
listbox-content—The column holding the title and description.
listbox-title—The option's name.
listbox-description—The supporting text.
listbox-group—A group of options.
listbox-group-label—The group's name.
listbox-separator—The line between groups.

Changelog

  1. registry 0.21.0

    e5495ef — size works the same way everywhere. Every component exports its size type (AlertSize, BadgeSize, CardSize, CheckboxSize, RadioSize, SwitchSize, EmptySize, InputFloatingSize, ItemSize, ListboxSize, SeparatorSize, SliderSize, StepperSize, TabsSize, TextareaSize, TimelineSize) and the props take it without null; Button-based parts take ButtonSize, Input TextControlSize, SelectTrigger SelectSize and Tree TreeSize. ToggleGroup and ToolbarToggleGroup carry data-size on the group as well. Table's row heights moved into tableSize, so a class on DataTable's ui.table overrides --table-row-h at every size, not only at md.

  2. registry 0.15.0

    d09f26a — Pressable parts ripple on their own: Button, Toggle, ToggleGroupItem, Item as a link or a button, the calendar days, tabs, accordion, menubar and navigation menu triggers, the items of Menu, Menubar, Select, Combobox, Command, DrawerMenu, Listbox and Tree, and the clear buttons of TagsInput and Combobox. Each imports the directive from @/lib/ripple, so add brings the ripple item along and nothing needs registering. On menu, listbox and tree rows the wave replaces the pressed layer, as state-layer already did. Bind v-ripple="false" on a Button to turn one off, or set --kappa-ripple: none on :root to turn them all off.

  3. registry 0.12.0

    81e522c — Listbox takes size, from xs to xl (default md), and sets data-size. Options are 28 to 48px tall and their padding, gap, icons and text follow the control scale, like a menu of the same size. At md the gap between an icon and its label is now 8px instead of 12px.

  4. registry 0.10.0

    8f31bd2 — New Command: a filterable list of commands over Reka UI's Listbox, ported from shadcn-vue, in Menu's five sizes: CommandInput, CommandList, CommandEmpty, CommandGroup, CommandLabel, CommandItem, CommandSeparator, CommandShortcut and CommandDialog.