Struct Combo

pub struct Combo<Msg: Clone> { /* private fields */ }

A combo / select / dropdown widget.

See the module-level documentation for the full wiring pattern. Build via combo and configure with the chained builders.

Implementations

impl<Msg: Clone> Combo<Msg>

pub fn new(state: ComboState, items: Vec<String>) -> Self

Construct a combo over items driven by state. Both arguments are taken by value because the widget tree is rebuilt every frame; clone the app’s state slice into here.

pub fn label(self, s: impl Into<String>) -> Self

Bold label drawn above the trigger.

pub fn description(self, s: impl Into<String>) -> Self

Optional descriptive paragraph drawn below the label.

pub fn placeholder(self, s: impl Into<String>) -> Self

Placeholder for the trigger’s text edit when the query is empty.

pub fn helper(self, s: impl Into<String>) -> Self

Helper / informative text below the trigger. Hidden when an error message is set.

pub fn error(self, s: impl Into<String>) -> Self

Error message below the trigger. Replaces the helper text and applies the destructive theme tokens to the trigger surface.

pub fn disabled(self, yes: bool) -> Self

Render in the disabled style. Activations / selections still emit messages — the consumer is responsible for ignoring them in update().

pub fn multi_select(self, yes: bool) -> Self

Allow multiple items to be selected at once. Selected items are rendered as chips above the trigger.

pub fn searchable(self, yes: bool) -> Self

Make the trigger an editable text field that filters the popup list as the user types. Without searchable, the trigger is a pressable button that displays the current selection.

pub fn max_chips_visible(self, n: usize) -> Self

Cap on the number of selection chips drawn above the trigger before falling back to a “+N more” indicator. Default 4.

pub fn anchor_id(self, id: WidgetId) -> Self

Stable identifier of the trigger pill. The popup looks the rect of this widget up in the previous frame’s layout snapshot to place itself flush below the trigger. Apps with several combos that may open simultaneously must give each a distinct id.

pub fn popup_gap(self, px: f32) -> Self

Vertical gap (logical pixels) between the bottom of the trigger and the top of the popup panel. Default 4.

pub fn popup_width(self, px: f32) -> Self

Width of the popup in logical pixels. Default 320.

pub fn popup_max_height(self, px: f32) -> Self

Maximum height of the popup before it scrolls internally. Default 280. The popup never grows past this height; it shrinks to fit the filtered item list when shorter.

pub fn on_query_change(self, f: impl Fn(String) -> Msg + 'static) -> Self

Callback fired with the new query string on every keystroke inside the trigger’s search field. Required when searchable( true ).

pub fn on_toggle_open(self, msg: Msg) -> Self

Message emitted when the user activates the trigger to toggle the popup open / closed (tap on the trigger pill or press the down-arrow icon button).

pub fn on_select_idx(self, f: impl Fn(usize) -> Msg + 'static) -> Self

Callback fired with the index of the item the user selects from the popup. The application’s update() should add that index to state.selected (multi-select) or replace it (single-select).

pub fn on_unselect_idx(self, f: impl Fn(usize) -> Msg + 'static) -> Self

Callback fired with the index of a chip the user dismisses (tapping its ×). Multi-select only.

pub fn on_dismiss(self, msg: Msg) -> Self

Message emitted when the user taps outside the popup. Typically flips state.is_open back to false in update().

pub fn filtered_indices(&self) -> Vec<usize>

Return the indices of items that match the current query (case insensitive contains match). Empty query passes every item.

impl<Msg: Clone + 'static> Combo<Msg>

pub fn trigger(&self) -> Element<Msg>

Build the trigger: label / description / chips (multi-select) / pill with text-edit + arrow / helper or error row. Returns an Element ready to drop into App::view.

pub fn popup(&self) -> Option<Element<Msg>>

Build the popup as a Stack-overlayable element. Returns None when the combo is closed.

The returned element is meant to be layered on top of the rest of the application’s view tree in the same surface — typically by wrapping the app’s view() output in a stack and pushing this element when it is Some. It already contains:

1. A full-surface dismiss layer behind the panel — a transparent pressable that fires Combo::on_dismiss when the user taps anywhere outside the panel.
2. The panel itself, centred horizontally and anchored 80 px from the top of the available rect, with the filtered item list inside a scrolling viewport bounded by Combo::popup_width and Combo::popup_max_height.

The popup centres modal-style — it does not anchor to the trigger position because the trigger’s screen-space rect is not known at view() time. For a trigger-anchored popup, drive the popup’s position from a runtime hint the application stores after the first hit-test.

pub fn overlay(&self) -> Option<OverlaySpec<Msg>>

Build the OverlaySpec that the application should return from App::overlays when this combo is open.

Returns None when the combo is closed.

Unlike Combo::popup, the overlay is rendered as a real Wayland xdg-popup child of the application’s main window — it can extend outside the parent surface (the canonical select / dropdown behaviour) and is positioned by the compositor relative to the trigger pill rect from the previous frame’s layout. The OverlayId is derived from Combo::anchor_id so two combos with distinct anchor ids get distinct overlay ids automatically.

The spec’s view is the panel itself (background, border, padding, rounded corners and the bounded scrolling item list). No extra dismiss layer is needed: tap-outside dismissal is handled by the usual ltk mechanism — wire App::on_tap to close the combo, or rely on the spec’s on_dismiss which fires when the compositor sends popup_done.