List Box — HeroGPUI

Usage

Labels use 14px text with 20px lines; descriptions and section headers use 12px text with 16px lines.

Live example

Rust

1use herogpui::prelude::{ListBox, ListBoxItem, SelectionMode};
2use gpui::prelude::*;
3use gpui::px;
4
5gpui::div()
6    .w(px(220.))
7    .child(ListBox::new(
8        "list-box",
9        vec![
10            ListBoxItem::new("inbox", "Inbox"),
11            ListBoxItem::new("sent", "Sent"),
12            ListBoxItem::new("drafts", "Drafts"),
13        ],
14    )
15    .selection_mode(SelectionMode::Single))

Live HeroGPUI compiled to WebAssembly. Select any example without loading another WASM instance.

Anatomy

Rust types

ListBoxListBoxItem

List Box is assembled from these builders. The API reference lists each one.

Customization

Appearance builders and theme tokens List Box uses.

Styling

List Box styling
Style	Description
`ListBox built-in text styles + Kbd::new().variant(Light)`	Built-in labels use 14px/20px medium text; descriptions and section headers use 12px/16px. Descriptions stack without a gap, and shortcuts reuse light Kbd.
`relative + w_full + overflow_hidden + padding 4px`	Full-width clipped list with four-pixel inset.
`gap 4px in row geometry`	Four pixels between direct collection records without flex-shrinking virtual content.
`FIELD_HEIGHT + gap(12) + soft_radius + px(8) + py(6)`	Option minimum height, 12px gap, 16px radius, and 8px/6px padding match.
`anim::pressed(PRESSED_SCALE_SUBTLE)`	Pressed geometry matches; uses its shared press timeline rather than the exact quart curve.
`colors.default.color hover`	Enabled pointer hover uses the default surface fill.
`inline trailing 16px indicator`	Size and default/danger colors match; flex layout places it at the trailing edge without the absolute logical-end positioning.
`ListBoxItemVariant::Danger`	Danger options and their indicator use the danger semantic color.
`ListBoxItem::Section row`	Flattens section heading records into the list rather than nesting a section container.
`separator margin and width`	Separators are centered at 94% width.

API reference

Builders

List Box builders
Builder	Type	Default	Description
`selection_mode(SelectionMode)`	`SelectionMode`	`SelectionMode::None`	Chooses inert, single, or multiple selection semantics; the wrapper sets no default, so the one applies.
`selected_keys(keys)`	`Selection`	—	Controlled selected keys; the owner must accept reported changes.
`default_selected_keys(keys)`	`Selection`	—	Seeds the list's uncontrolled selected-key set once.
`on_selection_change(callback)`	`Fn(keys: Selection) -> ()`	—	Reports the complete selected-key set after pointer and keyboard changes.
`disabled_keys(keys)`	`iterable of keys`	—	Removes matching options from pointer and keyboard selection stops.
`on_action(callback)`	`Fn(key: Key) -> ()`	—	Reports item activation independently from selection where gives action priority.
`variant(ListBoxItemVariant)`	`ListBoxItemVariant`	`ListBoxItemVariant::Default`	Default visual variant inherited by options unless an item overrides it.
`disallow_empty_selection(bool)`	`bool`	`false`	Inherited policy blocks the final-key toggle and Escape clearing.
`should_focus_wrap(bool)`	`bool`	`false`	Inherited policy joins the arrow-key ends.
`entry focus only`	`bool \| FocusStrategy`	`false`	Entry focus follows the selected key or first enabled option, but automatic mount focus is not exposed.
`escape_key_behavior(EscapeKeyBehavior)`	`EscapeKeyBehavior`	`EscapeKeyBehavior::ClearSelection`	Controls whether unmodified Escape clears a nonempty selection or remains available to an enclosing interaction.
`new(id, items)`	`id, items`	—	Items, sections, and separators are supplied as the constructor collection.
`new(key, label)`	`key, label`	—	Stable option identity used for selection and callbacks.
`is_disabled(bool)`	`bool`	`false`	Disables one option independently from disabledKeys.
`item_content(render)`	`AnyElement \| render closure`	—	Replacement row content receives selected, focused, focus-visible, pressed, and disabled state.
`indicator(render)`	`AnyElement \| render closure`	`checkmark`	Replaces the selected indicator and receives isSelected.
`section(label) / separator()`	`label / AnyElement`	—	Section headers and separators are explicit collection records.
`row_height(px)`	`px`	`48`	Fixed row geometry enables uniform-list virtualization; the virtual list caps at max_h, shrinks below it in a bounded parent, and pages by the visible viewport while skipping disabled stops.
`estimated_row_height(px)`	`px`	—	Estimated variable row geometry enables measured list virtualization.
`heading_height(px)`	`px`	`48`	Sets virtual section-row height.
`gap(px)`	`px`	`0`	Overrides the direct-child spacing.
`padding(px)`	`px`	`0`	Overrides the list inset.

Parts

List Box parts
Part	Description
`ListBox`	Selection, focus, keyboard, scrolling, and virtualization owner.
`ListBoxItem`	Selectable option with label, description, icon, shortcut, variant, and render state.
`ListBox`	Built-in check or caller-rendered selected marker.
`ListBoxItem`	Non-selectable heading record grouping following options; nested section ownership is flattened.

States

List Box states
Builder	State	Description
`selected_keys + indicator`	`Selected`	Selection is shown by the trailing indicator without adding a row fill.
`cursor keyed state`	`Focused`	Roving keyboard cursor tracks one enabled option.
`with_focus_ring + item_content`	`Focus visible`	Keyboard focus draws the status ring and reaches item render state.
`anim::pressed + interaction`	`Pressed`	Interactive options shrink to 98% and expose pressed render state.
`row hover chrome`	`Hovered`	Enabled options use the default hover fill; does not include hover in its documented item render-prop table.
`is_disabled / disabled_keys`	`Disabled`	Disabled options dim and leave pointer, arrow, typeahead, and selection stops.

Dropdown Tag Group