Listbox

A list of options that stays open on the page, from which the user picks one or several.

Select plan
Free
Starter
Team
Enterprise

Usage

Code
import { Listbox } from '@leverui/components';
Code
<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.

Select region
North America
South America
Europe
Asia Pacific
Selected: []

With Store

An alternative way to control the listbox is to use the RootProvider component and the useListbox store hook.

Select priority
Low
Medium
High
Urgent
Selected: []

This way you can access the listbox state and methods from outside the listbox.

Use RootProvider + useListbox or Root, not both.

Disabled Item

Disable specific items in the listbox to indicate unavailable options while keeping them visible for context.

Select size
Extra small
Small
Medium
Large
Extra large

Grouped

Use item groups to organize related options with clear section headers, making it easier for users to find specific categories of items.

Select media
Lanternwright
Saltwind
The Glass Orchard
The Quiet Harbor
Midnight Ferry
The Last Lighthouse

Horizontal

Display listbox items in a horizontal layout with card-based presentation, perfect for media galleries or visual selection interfaces.

Select album
Red Morning

Red Morning

Ada Linden

Violet Hour

Violet Hour

Night Ferry

Distant Light

Distant Light

The Far Field

Slow Tide

Slow Tide

Blue Harbor

Signal Lines

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 toppings (multiple)
Mushrooms
Olives
Peppers
Onions
Spinach
Tomatoes

Select All

Provide convenient "Select All" and "Select None" controls for multiple selection scenarios, with visual indicators showing selection state.

Ava Chen
Ben Ortiz
Chloe Martin
Daniel Kim
Elena Rossi
Farah Haddad
Gabriel Silva
Hana Sato
Isaac Moore
Jonah Price

Extended Select

Use extended selection mode to allow users to select multiple items using keyboard shortcuts like Cmd/Ctrl for advanced selection patterns.

Select files (hold โŒ˜ or ^ to select multiple)
report.pdf
budget.xlsx
notes.txt
photo.jpg

With Checkmark

Display custom checkmarks for multiple selection scenarios, providing clear visual feedback for selected items.

Select channels (with checkmarks)
Email
Text message
Push notification
In-app message
Weekly digest
Phone call

With Icon

Add icons to listbox items to provide visual context and improve recognition of different options.

Select topic
Science
Art
Travel
Energy

With Description

Include additional descriptive text for each item to provide more context and help users make informed choices.

Select shipping method
Standard

5 to 7 business days

Express

2 to 3 business days

Overnight

Next business day

Pickup

Ready in 2 hours

Freight

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.

Select fruit
Apple
Apricot
Banana
Blueberry
Cherry
Grape
Lemon
Mango
Orange
Peach

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.

Select day

Home and End highlight the first and last item instead of moving the text caret.

Monday
Tuesday
Wednesday
Thursday
Friday

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.

Select country (249 items)

Image Explorer

Create an interactive gallery where the listbox acts as navigation for displaying different images or media content.

Transfer List

Create a dual-listbox interface for moving items between available and selected states, commonly used for permission management or item selection workflows.

Available characters
Wren
Corin
Mira
Tobin
Ansel
Juniper
Calla
Dorian
Elsie
Fenwick
Greta
Hollis
Isolde
Jasper
Linnea
Selected characters
No items available

Emoji Grid

Display emojis in a grid layout with filtering capability, perfect for emoji pickers or icon selection interfaces.

Emojis
๐Ÿ˜€
๐Ÿ˜ƒ
๐Ÿ˜„
๐Ÿ˜
๐Ÿ˜†
๐Ÿ˜…
๐Ÿคฃ
๐Ÿ˜‚
๐Ÿ™‚
๐Ÿ™ƒ
๐Ÿซ 
๐Ÿ˜‰
๐Ÿ˜Š
๐Ÿ˜‡
๐Ÿฅฐ
๐Ÿ˜
๐Ÿคฉ
๐Ÿ˜˜
๐Ÿ˜—
โ˜บ๏ธ
๐Ÿ˜š
๐Ÿ˜™
๐Ÿฅฒ
๐Ÿ˜‹
๐Ÿ˜›
๐Ÿ˜œ
๐Ÿคช
๐Ÿ˜
๐Ÿค‘
๐Ÿค—
๐Ÿคญ
๐Ÿซข
๐Ÿซฃ
๐Ÿคซ
๐Ÿค”
๐Ÿซก
๐Ÿค
๐Ÿคจ
๐Ÿ˜
๐Ÿ˜‘
๐Ÿ˜ถ
๐Ÿซฅ
๐Ÿ˜ถโ€๐ŸŒซ๏ธ
๐Ÿ˜
๐Ÿ˜’
๐Ÿ™„
๐Ÿ˜ฌ
๐Ÿ˜ฎโ€๐Ÿ’จ
๐Ÿคฅ
๐Ÿซจ
๐Ÿ™‚โ€โ†”๏ธ
๐Ÿ™‚โ€โ†•๏ธ
๐Ÿ˜Œ
๐Ÿ˜”
๐Ÿ˜ช
๐Ÿคค
๐Ÿ˜ด
๐Ÿซฉ
๐Ÿ˜ท
๐Ÿค’
๐Ÿค•
๐Ÿคข
๐Ÿคฎ
๐Ÿคง
๐Ÿฅต
๐Ÿฅถ
๐Ÿฅด
๐Ÿ˜ต
๐Ÿ˜ตโ€๐Ÿ’ซ
๐Ÿคฏ
๐Ÿค 
๐Ÿฅณ
๐Ÿฅธ
๐Ÿ˜Ž
๐Ÿค“
๐Ÿง
๐Ÿ˜•
๐Ÿซค
๐Ÿ˜Ÿ
๐Ÿ™
โ˜น๏ธ
๐Ÿ˜ฎ
๐Ÿ˜ฏ
๐Ÿ˜ฒ
๐Ÿ˜ณ
๐Ÿซช
๐Ÿฅบ
๐Ÿฅน
๐Ÿ˜ฆ
๐Ÿ˜ง
๐Ÿ˜จ
๐Ÿ˜ฐ
๐Ÿ˜ฅ
๐Ÿ˜ข
๐Ÿ˜ญ
๐Ÿ˜ฑ
๐Ÿ˜–
๐Ÿ˜ฃ
๐Ÿ˜ž
๐Ÿ˜“
๐Ÿ˜ฉ
๐Ÿ˜ซ
๐Ÿฅฑ
๐Ÿ˜ค
๐Ÿ˜ก
๐Ÿ˜ 
๐Ÿคฌ
๐Ÿ˜ˆ
๐Ÿ‘ฟ
๐Ÿ’€
โ˜ ๏ธ
๐Ÿ’ฉ
๐Ÿคก
๐Ÿ‘น
๐Ÿ‘บ
๐Ÿ‘ป
๐Ÿ‘ฝ
๐Ÿ‘พ
๐Ÿค–
๐Ÿ˜บ
๐Ÿ˜ธ
๐Ÿ˜น
๐Ÿ˜ป
๐Ÿ˜ผ
๐Ÿ˜ฝ
๐Ÿ™€
๐Ÿ˜ฟ
๐Ÿ˜พ
๐Ÿ™ˆ
๐Ÿ™‰
๐Ÿ™Š
๐Ÿ’Œ
๐Ÿ’˜
๐Ÿ’
๐Ÿ’–
๐Ÿ’—
๐Ÿ’“
๐Ÿ’ž
๐Ÿ’•
๐Ÿ’Ÿ
โฃ๏ธ
๐Ÿ’”
โค๏ธโ€๐Ÿ”ฅ
โค๏ธโ€๐Ÿฉน
โค๏ธ
๐Ÿฉท
๐Ÿงก
๐Ÿ’›
๐Ÿ’š
๐Ÿ’™
๐Ÿฉต
๐Ÿ’œ
๐ŸคŽ
๐Ÿ–ค
๐Ÿฉถ
๐Ÿค
๐Ÿ’‹
๐Ÿ’ฏ
๐Ÿ’ข
๐Ÿซฏ
๐Ÿ’ฅ
๐Ÿ’ซ
๐Ÿ’ฆ
๐Ÿ’จ
๐Ÿ•ณ๏ธ
๐Ÿ’ฌ
๐Ÿ‘๏ธโ€๐Ÿ—จ๏ธ
๐Ÿ—จ๏ธ
๐Ÿ—ฏ๏ธ
๐Ÿ’ญ
๐Ÿ’ค
๐Ÿ‘‹
๐Ÿคš
๐Ÿ–๏ธ
โœ‹
๐Ÿ––
๐Ÿซฑ
๐Ÿซฒ
๐Ÿซณ
๐Ÿซด
๐Ÿซท
๐Ÿซธ
๐Ÿ‘Œ
๐ŸคŒ
๐Ÿค
โœŒ๏ธ
๐Ÿคž
๐Ÿซฐ
๐ŸคŸ
๐Ÿค˜
๐Ÿค™
๐Ÿ‘ˆ
๐Ÿ‘‰
๐Ÿ‘†
๐Ÿ–•
๐Ÿ‘‡
โ˜๏ธ
๐Ÿซต
๐Ÿ‘
๐Ÿ‘Ž

Props

Root

PropDefaultTypeDescription
collection*โ€”ListCollection<T>Collection that holds the items.
defaultValue[]string[]Selected values on first render. Uncontrolled.
orientationvertical'horizontal' | 'vertical'Direction the items are laid out in.
selectionModesingle'single' | 'multiple' | 'extended'single: one item. multiple: several, no modifier key. extended: several with a modifier key.
colorPalettegraystringColor palette, built-in or your own.
variantsubtle'subtle' | 'solid' | 'plain'Listbox style.
asdivNative HTML tagHTML tag to render.
asChildโ€”Solid render functionRender your own element with the part's props.
unstyledโ€”booleanTurn off the Lever UI styles.
defaultHighlightedValueโ€”stringHighlighted item's value on first open. Uncontrolled.
deselectableโ€”booleanLet the user deselect the selected item.
disabledโ€”booleanDisable the listbox.
disallowSelectAllโ€”booleanStop meta+a from selecting every item.
highlightedValueโ€”stringHighlighted item's value. Controlled.
idโ€”stringUnique id for the listbox.
idsโ€”Element ID mapIds for the listbox's elements. For use with other components.
loopFocusfalsebooleanWrap keyboard navigation from the last option to the first.
onHighlightChangeโ€”(details) => voidCalled when the highlighted item changes.
onSelectโ€”(details) => voidCalled when an item is selected.
onValueChangeโ€”(details) => voidCalled when the selected item changes.
scrollToIndexFnโ€”(details) => voidScrolls to the item at a given index.
selectOnHighlightโ€”booleanSelect an item as soon as it is highlighted.
typeaheadโ€”booleanTyping 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

PropDefaultTypeDescription
asspanNative HTML tagHTML tag to render.
asChildโ€”Solid render functionRender your own element with the part's props.

Input

PropDefaultTypeDescription
keyboardPrioritycaret'caret' | 'navigate'For keys that could edit text or move the list. caret: edit text. navigate: send supported keys to the listbox.
asinputNative HTML tagHTML tag to render.
asChildโ€”Solid render functionRender your own element with the part's props.
autoHighlightfalsebooleanHighlight the item as you type.

Content

Styled box around List. Headers, footers, Empty, and Status go inside it, next to List.

PropDefaultTypeDescription
asdivNative HTML tagHTML tag to render.
asChildโ€”Solid render functionRender 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.

PropDefaultTypeDescription
asdivNative HTML tagHTML tag to render.
asChildโ€”Solid render functionRender your own element with the part's props.

Item

PropDefaultTypeDescription
asdivNative HTML tagHTML tag to render.
asChildโ€”Solid render functionRender your own element with the part's props.
highlightOnHoverโ€”booleanHighlight the item on pointer hover.
itemโ€”anyItem to render.

ItemText

PropDefaultTypeDescription
asspanNative HTML tagHTML tag to render.
asChildโ€”Solid render functionRender your own element with the part's props.

ItemIndicator

PropDefaultTypeDescription
asdivNative HTML tagHTML tag to render.
asChildโ€”Solid render functionRender your own element with the part's props.

ItemGroup

PropDefaultTypeDescription
asdivNative HTML tagHTML tag to render.
asChildโ€”Solid render functionRender your own element with the part's props.

ItemGroupLabel

PropDefaultTypeDescription
asdivNative HTML tagHTML tag to render.
asChildโ€”Solid render functionRender 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.

Code
.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