Listbox

Option list on the page: one or several, Shift ranges. Free, MIT · Forms and input › Selects

A list of options that stays on the page (WAI-ARIA listbox, React Aria's ListBox): one or several selected, the arrows, Home / End, Page keys and type-ahead move the highlight, and with multiple Shift+click and Shift+arrows select ranges. Props not listed go to the listbox element.

Installation

npx valyro-cli@latest add listbox

npx shadcn@latest add https://valyro.xyz/r/listbox.json

npm install valyro-ui

import 'valyro-ui/styles.css';
import { Listbox } from 'valyro-ui';

Props

Prop	Type	Default
`options`	`SelectItem[]`		Options, flat or in labelled groups. Or compose them as children: `Listbox.Item`, `Listbox.Group`, `Listbox.Empty`.
`children`	`ReactNode`		The compound form instead of `options`: `Listbox.Item`, `Listbox.Group` and `Listbox.Empty` elements.
`multiple`	`boolean`	`false`	Several options can be selected: checkboxes, Shift ranges, Ctrl/Cmd+A, Escape to clear.
`value`	`string[]`		Selected values (at most one without `multiple`), in the order they were picked.
`defaultValue`	`string[]`		Initial `value` when uncontrolled.
`onValueChange`	`(value: string[]) => void`		Called with the new `value` when it changes.
`selectionBehavior`	`'toggle' \| 'replace'`		`toggle` (default): a click, Enter or Space picks or toggles an option, the arrows only move. `replace`: a click or an arrow selects that option alone, as in a file list; Ctrl/Cmd+click and Ctrl/Cmd+Space add or remove one.
`emptyText`	`ReactNode`		Shown instead of the list when there are no options; announced politely.
`name`	`string`		Submits the selected values with the surrounding form, one hidden input each.
`required`	`boolean`		At least one option must be selected: `aria-required`, and the surrounding form does not submit without one.
`disabled`	`boolean`	`false`	Every option is disabled and the list leaves the tab order.
`invalid`	`boolean`	`false`	Error border and `aria-invalid` (an explicit `aria-invalid` wins).

Compound parts

Listbox.Item (ListboxItem), Listbox.Group (ListboxGroup), Listbox.Empty (ListboxEmpty)

Related components

Select — Pick one option from a list
Multi Select — Pick several options
Combobox — Searchable select
Chip Group — Chip group with icons: one or several options
Checkbox Tree — Checkbox tree: cascading, indeterminate state, keyboard
Text Input — Text fields
Textarea — Multiline text input
Search Input — Search field
Mentions Input — Text with @mentions and #tags, async suggestions
Tags Input — Tag entry
Checkbox — Checkboxes
Checkbox Group — Checkboxes under one label, hint, error and requirement

Previous: Combobox · Next: Chip Group · All Forms and input