Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Select

Layer: organism · Path: src/organisms/select.rs · Exports: select::Select

A dropdown single-select (shadcn Select / Unity Dropdown / O3DE Dropdown): a trigger Button showing the current option + a egui::Popup::menu of MenuItem cells. Bound to a &mut usize index — clicking an item writes the index and closes the popup. show returns the trigger Response.

Design

  • Purpose / when to use — pick one value from a fixed list (blend mode, quality level). For arbitrary anchored content use Popover; for command menus use DropdownMenu.

  • Anatomy — trigger: Button (Outline variant, right-side CARET_DOWN glyph, keyed "select_trigger") showing the selected option or placeholder → Popup::menu on its response → one MenuItem per option (keyed ("select", i)).

  • Variants / states

    StateHow
    no/invalid selectiontrigger shows placeholder (default "Select…")
    selectedtrigger shows options[*selected]
    option clickedwrites *selected = i, calls ui.close()
    sizeSize::Sm / Md (default) / Lg via .size / .sm() / .lg()

  • Tokens / layout consumed — trigger height follows the shared Size scale (hover animation lives in Button); themed menu frame via Popup.

  • Layering — uses egui::Popup anchored to the trigger; themed menu frame is the casing.

  • Accessibility — Popup dismiss on outside-click / Esc; selection closes.

API

MethodEffect
Select::new(selected: &'a mut usize) -> SelfBind to a selection index.
.options<S: Into<String>>(options: impl IntoIterator<Item = S>) -> SelfSet the option labels.
.placeholder(text: impl Into<String>) -> SelfText shown when the index is out of range (default "Select…").
.size(size: Size) -> SelfSet trigger size.
.sm() -> Self / .lg() -> SelfSize shortcuts.
.show(ui) -> ResponseRender trigger + popup; on click writes *selected. Returns the trigger Response.

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::organisms::Select;

let mut sel = 0usize;
Select::new(&mut sel)
    .options(["Opaque", "Cutout", "Transparent"])
    .placeholder("Blend mode…")
    .show(ui);
}
#![allow(unused)]
fn main() {
// realistic — persist selection across frames (from storybook)
use ouroboros_ui::organisms::Select;

let id = egui::Id::new("select_demo");
let mut sel = ui.data(|d| d.get_temp::<usize>(id).unwrap_or(0));
Select::new(&mut sel)
    .options(["Opaque", "Cutout", "Transparent", "Additive"])
    .placeholder("Blend mode…")
    .show(ui);
ui.data_mut(|d| d.insert_temp(id, sel));
}

Composition

Overlay organism: a Button atom trigger + the egui::Popup::menu container holding MenuItem cells. It never paints — see guards.

Notes

  • State ownership — the consumer owns the &mut usize; persist it yourself (e.g. egui temp data) to survive frames, as the storybook does.
  • An out-of-range index renders the placeholder rather than panicking.
  • The trigger id is fixed ("select_trigger"); push a unique ui.push_id(...) scope when rendering several selects in one container (storybook does this for the size row).