Listbox

Present selectable options in a popup with search filtering and keyboard support, including Select panels.

We are building SnowUI components into interfaces people can use directly in AI conversations. Conversational UI is still in development; this page demonstrates website usage. Supported chat platforms and component versions will be announced after verification. Generating and using SnowUI interfaces inside AI conversations is completely free. It is not a project, uses no project or developer-seat quota, and requires no SnowUI registration, activation, or paid proof.

How to use

Use Listbox for an option panel with keyboard navigation and selection semantics, usually hosted by Select. Notifications, contacts, and activity feeds are content lists and do not use Listbox.

Each item needs a unique value; label provides display text and search text. children replaces the generated items.
For explicit options, use MenuItem as="item". For an explicit search field, use Input as="search" and disable built-in search to avoid duplicate inputs.
The generated search placeholder follows LocaleProvider through listbox.search. Explicit parts.Input.placeholder values, including an empty string, and native aria-label values retain priority. Configure explicit Input children yourself; query text and option content are not translated.

Import

import { Listbox } from '@snowui-design-system/components';

Usage

Custom categories

Page status

Long lists

Placement

Width and alignment

Hover feedback

Selection mark

API Reference

Property	Type	Default	Example	Description
`children`	`Snippet`	`—`	`<Select><Listbox search={false}><MenuItem as="item" value="guides">Guides</MenuItem></Listbox></Select>`	Explicit option content without arguments. Replaces items. Give each MenuItem as="item" a unique value. For external search, use Input as="search" and set search={false}.
`items`	`ListboxItem[]`	`[]`	`items={[{ value: "guides", label: "Guides" }, { value: "archive", label: "Archive", disabled: true }]}`	Built-in options with a required unique string value, a display and search label, and optional disabled state. Ignored when children is supplied; the host manages custom runtime items.
`parts`	`ComponentPartsOf<{ Input: typeof Input; MenuItem: typeof MenuItem; Text: typeof Text; }>`	`—`	`parts={{ Input: { placeholder: "Find a component…" } }}`	Configure public Props of generated Input, MenuItem and string-label Text instances, including search placeholders, custom values, check marks and label typography. parts.Text only applies to generated items and custom-option labels; configure explicit children directly. parts.MenuItem.showCheck takes priority over the Listbox showCheck default.
`search`	`boolean`	`—`	`search`	Whether to add a fixed search Input at the top. Resolves from the explicit value, host configuration, then true. Select supplies false by default; enable it explicitly when needed.
`maxHeight`	`number \| string`	`—`	`maxHeight={200}`	Maximum panel height. A number means pixels; a string is a CSS length. Limited by viewport space. Without a value, shows up to 10 complete items and retains at least the first two actual options when space is short.
`minWidth`	`number \| string`	`—`	`minWidth={120}`	Minimum panel width. A number means pixels; a string is a CSS length. Without a value, defaults to 160px with search or 0 without search. Content and viewport limits still affect final width.
`scrollbar`	`boolean`	`true`	`scrollbar`	Show the overlay scrollbar when content overflows. false hides only the track; wheel and keyboard scrolling still work.
`matchTriggerWidth`	`boolean`	`true`	`matchTriggerWidth`	With true, start from measured anchor width plus 2px, covering 1px on each side; wider content may expand the panel. With false, hug option content without compensation, subject to minWidth and viewport limits.
`placementMode`	`"selected" \| "bottom"`	`"selected"`	`placementMode="selected"`	selected centers the chosen item on the trigger; bottom opens below the trigger. Available viewport space constrains final position and height.
`align`	`"start" \| "end"`	`"start"`	`align="start"`	Align the panel to the left or right edge of its anchor. The difference is visible when a content-width panel differs from its anchor; viewport limits still apply.
`showCheck`	`boolean`	`false`	`showCheck`	Reserve space for and show a trailing check on the selected item. Select supplies true by default. An explicit MenuItem can override it, and a custom trailing item replaces the built-in check.
`continuousHover`	`boolean`	`true`	`continuousHover`	Move one highlight background between direct MenuItem entries, shared with keyboard active state. false restores each item’s immediate background. Disabled and filtered entries are not targets.