List

An input and layout view for displaying a scrollable collection of items.

When To Use It

Use List when you need to present a sequence of items that users can browse, focus, and optionally select. Lists work well for settings panels, menus, search results, file views, and other repeated content where each item shares the same structure.

Constructing a List

A List takes a reactive or static collection and a closure used to build each item view. The list automatically creates and updates internal signals for each item.

let items = Signal::new(vec!["One", "Two", "Three"]);

List::new(cx, items, |cx, _, item| {
	Label::new(cx, item).hoverable(false);
})
.selectable(Selectable::Single)
.on_select(|cx, index| cx.emit(AppEvent::SelectItem(index)));

Use modifiers such as orientation, selection_follows_focus, and scrollbar controls to change behavior:

List::new(cx, items, |cx, index, item| {
	Label::new(cx, item)
		.toggle_class("dark", index % 2 == 0)
		.width(Stretch(1.0))
		.height(Pixels(30.0))
		.hoverable(false);
})
.selectable(Selectable::Single)
.selection_follows_focus(true)
.orientation(Orientation::Horizontal)
.show_vertical_scrollbar(false)
.show_horizontal_scrollbar(true);

List Modifiers

Components and Styling

A List renders as a list element containing an internal scrollview, with each item rendered as a list-item.

Theming

Customize list items using the list and item selectors:

list list-item {
	padding-left: 8px;
	padding-right: 8px;
}

list.selectable list-item:hover {
	background-color: var(--accent);
}

list.selectable list-item:checked {
	background-color: var(--primary);
}

Accessibility

The list has a role of List, and each item has a role of ListItem. Focus and selection are exposed separately: keyboard navigation moves focus, and selection changes based on the configured selection mode.

Adding a Label

To associate visible text with a list, give the label an identifier and associate the list with it using labeled_by:

VStack::new(cx, |cx| {
	Label::new(cx, "Themes").id("themes_list_label");

	List::new(cx, items, |cx, _, item| {
		Label::new(cx, item).hoverable(false);
	})
	.labeled_by("themes_list_label")
	.selectable(Selectable::Single);
})
.height(Auto)
.gap(Pixels(8.0));

Using name Without a Label

If no visible label is present, provide an accessible name directly on the list with name:

List::new(cx, items, |cx, _, item| {
	Label::new(cx, item).hoverable(false);
})
.name("Themes")
.selectable(Selectable::Single);

Use this for compact layouts where a separate label is not shown.

Pointer Interaction

Users can interact with the list using the pointer in the following ways:

• Click a list-item to focus the list and apply selection for that item.
• In Selectable::Single, clicking the selected item again clears selection when min_selected is 0.
• In Selectable::Multi, clicking toggles an item on or off, subject to min_selected and max_selected.

Keyboard Interaction