Listbox
A list of options that stays open on the page, from which the user picks one or several.
Usage
import { Listbox } from '@leverui/components';
<Listbox.Root>
<Listbox.Label />
<Listbox.Content>
<Listbox.List>
<Listbox.Item>
<Listbox.ItemText />
<Listbox.ItemIndicator />
</Listbox.Item>
</Listbox.List>
</Listbox.Content>
</Listbox.Root>
Options come from a list collection. Use useListCollection, or
createListCollection for fixed items, and pass the collection to Root. A
useListCollection collection is an accessor: call collection() to read it.
Listbox.Label gives the accessible name. The indicator shows a check icon
unless you pass it a child. Give each option clear text, and hide decorative
icons from assistive technology. Listbox.useListboxItemContext() returns
reactive selected and disabled values for an item.
Examples
Controlled
Control the listbox value externally using the value and onValueChange props for custom state management.
Selected: []With Store
An alternative way to control the listbox is to use the RootProvider component and the useListbox store hook.
Selected: []This way you can access the listbox state and methods from outside the listbox.
Use
RootProvider + useListboxorRoot, not both.
Disabled Item
Disable specific items in the listbox to indicate unavailable options while keeping them visible for context.
Grouped
Use item groups to organize related options with clear section headers, making it easier for users to find specific categories of items.
Horizontal
Display listbox items in a horizontal layout with card-based presentation, perfect for media galleries or visual selection interfaces.

Red Morning
Ada Linden

Violet Hour
Night Ferry

Distant Light
The Far Field

Slow Tide
Blue Harbor

Signal Lines
Paper Circuit
Multiple Selection
Enable users to select multiple items from the list, useful for scenarios like choosing tags, categories, or preferences.
Select All
Provide convenient "Select All" and "Select None" controls for multiple selection scenarios, with visual indicators showing selection state.
Extended Select
Use extended selection mode to allow users to select multiple items using keyboard shortcuts like Cmd/Ctrl for advanced selection patterns.
With Checkmark
Display custom checkmarks for multiple selection scenarios, providing clear visual feedback for selected items.
With Icon
Add icons to listbox items to provide visual context and improve recognition of different options.
With Description
Include additional descriptive text for each item to provide more context and help users make informed choices.
5 to 7 business days
2 to 3 business days
Next business day
Ready in 2 hours
Large orders, 7 to 10 business days
With Input
Combine a search input with the listbox to filter options dynamically, making it easy to find specific items in long lists.
Keyboard Priority
Set keyboardPriority="navigate" on Listbox.Input so Home and End move the highlighted item instead of the text caret. The default caret mode preserves native text editing behavior.
Home and End highlight the first and last item instead of moving the text caret.
With Popover
Use the listbox within a popover to create dropdown-like selection menus that overlay other content without taking up permanent screen space.
With Dialog
Present the listbox in a modal dialog for focused selection experiences, particularly useful for important choices that need user attention.
Virtualized
Handle large datasets efficiently with virtualization, rendering only visible items to maintain smooth scrolling performance even with thousands of items.
Image Explorer
Create an interactive gallery where the listbox acts as navigation for displaying different images or media content.
Snowy peaks

Mountains under a pink evening sky
Transfer List
Create a dual-listbox interface for moving items between available and selected states, commonly used for permission management or item selection workflows.
Emoji Grid
Display emojis in a grid layout with filtering capability, perfect for emoji pickers or icon selection interfaces.
Props
Root
| Prop | Default | Type | Description |
|---|---|---|---|
collection* | โ | ListCollection<T> | Collection that holds the items. |
defaultValue | [] | string[] | Selected values on first render. Uncontrolled. |
orientation | vertical | 'horizontal' | 'vertical' | Direction the items are laid out in. |
selectionMode | single | 'single' | 'multiple' | 'extended' | single: one item. multiple: several, no modifier key. extended: several with a modifier key. |
colorPalette | gray | string | Color palette, built-in or your own. |
variant | subtle | 'subtle' | 'solid' | 'plain' | Listbox style. |
as | div | Native HTML tag | HTML tag to render. |
asChild | โ | Solid render function | Render your own element with the part's props. |
unstyled | โ | boolean | Turn off the Lever UI styles. |
defaultHighlightedValue | โ | string | Highlighted item's value on first open. Uncontrolled. |
deselectable | โ | boolean | Let the user deselect the selected item. |
disabled | โ | boolean | Disable the listbox. |
disallowSelectAll | โ | boolean | Stop meta+a from selecting every item. |
highlightedValue | โ | string | Highlighted item's value. Controlled. |
id | โ | string | Unique id for the listbox. |
ids | โ | Element ID map | Ids for the listbox's elements. For use with other components. |
loopFocus | false | boolean | Wrap keyboard navigation from the last option to the first. |
onHighlightChange | โ | (details) => void | Called when the highlighted item changes. |
onSelect | โ | (details) => void | Called when an item is selected. |
onValueChange | โ | (details) => void | Called when the selected item changes. |
scrollToIndexFn | โ | (details) => void | Scrolls to the item at a given index. |
selectOnHighlight | โ | boolean | Select an item as soon as it is highlighted. |
typeahead | โ | boolean | Typing moves to the matching item. |
value | โ | string[] | Selected values. Controlled. |
Listbox.useListbox returns an accessor for the state machine. Pass it to
Listbox.RootProvider as value. Listbox.Context and Listbox.ItemContext
give the machine's reactive state. Listbox.useListboxContext() reads it
inside the root.
Listbox.PropsProvider sets default props for the listboxes inside it, from an
object or an accessor. A prop on a listbox wins. On RootProvider, defaults
change only the look, not the collection or selection.
Not a native form control, so a form does not submit its selection. Use
onValueChange to copy the value into a form field.
Label
| Prop | Default | Type | Description |
|---|---|---|---|
as | span | Native HTML tag | HTML tag to render. |
asChild | โ | Solid render function | Render your own element with the part's props. |
Input
| Prop | Default | Type | Description |
|---|---|---|---|
keyboardPriority | caret | 'caret' | 'navigate' | For keys that could edit text or move the list. caret: edit text. navigate: send supported keys to the listbox. |
as | input | Native HTML tag | HTML tag to render. |
asChild | โ | Solid render function | Render your own element with the part's props. |
autoHighlight | false | boolean | Highlight the item as you type. |
Content
Styled box around List. Headers, footers, Empty, and Status go inside it,
next to List.
| Prop | Default | Type | Description |
|---|---|---|---|
as | div | Native HTML tag | HTML tag to render. |
asChild | โ | Solid render function | Render your own element with the part's props. |
List
Has the listbox role, takes keyboard focus and tracks the active item. Items and item groups go inside it.
| Prop | Default | Type | Description |
|---|---|---|---|
as | div | Native HTML tag | HTML tag to render. |
asChild | โ | Solid render function | Render your own element with the part's props. |
Item
| Prop | Default | Type | Description |
|---|---|---|---|
as | div | Native HTML tag | HTML tag to render. |
asChild | โ | Solid render function | Render your own element with the part's props. |
highlightOnHover | โ | boolean | Highlight the item on pointer hover. |
item | โ | any | Item to render. |
ItemText
| Prop | Default | Type | Description |
|---|---|---|---|
as | span | Native HTML tag | HTML tag to render. |
asChild | โ | Solid render function | Render your own element with the part's props. |
ItemIndicator
| Prop | Default | Type | Description |
|---|---|---|---|
as | div | Native HTML tag | HTML tag to render. |
asChild | โ | Solid render function | Render your own element with the part's props. |
ItemGroup
| Prop | Default | Type | Description |
|---|---|---|---|
as | div | Native HTML tag | HTML tag to render. |
asChild | โ | Solid render function | Render your own element with the part's props. |
ItemGroupLabel
| Prop | Default | Type | Description |
|---|---|---|---|
as | div | Native HTML tag | HTML tag to render. |
asChild | โ | Solid render function | Render your own element with the part's props. |
Customize with CSS
Import @leverui/components/styles.css once. variant is responsive, such as
variant={{ base: 'plain', md: 'solid' }}, and shows on the element as
data-variant attributes. colorPalette on the root sets the selection color
solid uses.
class and style work on the root and on any part. Each part has a stable
class name.
.my-listbox {
--leverui-listbox-content-max-height: 18rem;
--leverui-listbox-selected-background: #fef08a;
}
.my-listbox .leverui-listbox__item {
border-radius: 0.75rem;
}
unstyled on the root turns off the Lever UI styles for every part. On one
part, it resets only that part. Selection, focus, and accessibility attributes
keep working. With asChild, keep the part's props on your element so focus
and keyboard behavior still work.
Explorer
Click a part name in the sidebar to highlight it in the preview.
Component Anatomy
Hover to highlight, click to select parts