Select

A single- or multiple-choice picker whose option surface is rendered in a native popover window.

#Import

Import Select from quickgui.

use quickgui::*;

#Usage

let mut state = SelectState::new(items);
state.open(true);
div().child(text(state.selected_label().unwrap_or("Choose")))

#Anatomy

Select::root
Select::trigger
Select::option_part
Select::label
Select::value
Select::icon
Select::backdrop
Select::portal
Select::positioner
Select::popup
Select::arrow
Select::list
Select::item
Select::item_text
Select::item_indicator
Select::group
Select::group_label
Select::separator
Select::scroll_up_arrow
Select::scroll_down_arrow

#API reference

Expand an entry for its description and complete signature. A dash means no declaration default is documented.

`SelectState`

View source

pub fn new(items: impl IntoIterator<Item = PickerItem<T>>) -> Result<Self, PickerError>

with_layoutpub fn with_layout(mut self, layout: SelectPopoverLayout) -> Self—

Configures with layout for this part.

pub fn with_layout(mut self, layout: SelectPopoverLayout) -> Self

View source

layoutpub fn layout(&self) -> SelectPopoverLayout—

Configures layout for this part.

pub fn layout(&self) -> SelectPopoverLayout

View source

set_layoutpub fn set_layout(&mut self, layout: SelectPopoverLayout) -> bool—

Configures set layout for this part.

pub fn set_layout(&mut self, layout: SelectPopoverLayout) -> bool

View source

itemspub fn items(&self) -> &[PickerItem<T>]—

Configures items for this part.

pub fn items(&self) -> &[PickerItem<T>]

View source

from_labelspub fn from_labels( items: impl IntoIterator<Item = (T, impl Into<Arc<str>>)>, ) -> Result<Self, PickerError>—

Create a select from Base UI's `items` map form, one entry per value and its label. This is the shortest declaration for a select whose options are a fixed value-to-label mapping; [`Self::new`] stays available for options that need stable IDs or disabled rows.

pub fn from_labels( items: impl IntoIterator<Item = (T, impl Into<Arc<str>>)>, ) -> Result<Self, PickerError>

View source

selected_source_indexpub fn selected_source_index(&self) -> Option<usize>—

The first selected source index, or `None` when nothing is selected.

pub fn selected_source_index(&self) -> Option<usize>

View source

selected_source_indicespub fn selected_source_indices(&self) -> &[usize]—

Every selected source index, ascending, Base UI's `multiple` value array. A single select holds at most one entry; a multiple select holds at most [`MAX_SELECT_VALUES`].

pub fn selected_source_indices(&self) -> &[usize]

View source

selected_itemspub fn selected_items(&self) -> impl Iterator<Item = &PickerItem<T>>—

Every selected item, in source order.

pub fn selected_items(&self) -> impl Iterator<Item = &PickerItem<T>>

View source

selected_valuespub fn selected_values(&self) -> impl Iterator<Item = &T>—

Every selected value, in source order.

pub fn selected_values(&self) -> impl Iterator<Item = &T>

View source

value_textpub fn value_text(&self) -> Option<Arc<str>>—

The joined label text a trigger shows, Base UI's `Select.Value`. Returns `None` when nothing is selected, which is when Base UI renders the placeholder.

pub fn value_text(&self) -> Option<Arc<str>>

View source

value_separatorpub fn value_separator(mut self, separator: impl Into<Arc<str>>) -> Self—

Replace the separator joining a multiple select's value text.

pub fn value_separator(mut self, separator: impl Into<Arc<str>>) -> Self

View source

multiplepub fn multiple(mut self, multiple: bool) -> Self—

Accept more than one value, Base UI's `multiple`. Turning `multiple` off keeps only the first selected value, so the retained set can never disagree with the declared arity.

pub fn multiple(mut self, multiple: bool) -> Self

View source

set_multiplepub fn set_multiple(&mut self, multiple: bool) -> bool—

Replace the multiple flag in place, reporting whether anything changed.

pub fn set_multiple(&mut self, multiple: bool) -> bool

View source

is_multiplepub const fn is_multiple(&self) -> bool—

Configures is multiple for this part.

pub const fn is_multiple(&self) -> bool

View source

requiredpub const fn required(mut self, required: bool) -> Self—

Require a value before submission, Base UI's `required`.

pub const fn required(mut self, required: bool) -> Self

View source

is_requiredpub const fn is_required(&self) -> bool—

Configures is required for this part.

pub const fn is_required(&self) -> bool

View source

read_onlypub const fn read_only(mut self, read_only: bool) -> Self—

Refuse value changes while staying focusable, Base UI's `readOnly`.

pub const fn read_only(mut self, read_only: bool) -> Self

View source

is_read_onlypub const fn is_read_only(&self) -> bool—

Configures is read only for this part.

pub const fn is_read_only(&self) -> bool

View source

modalpub const fn modal(mut self, modal: bool) -> Self—

Contain focus and expect a mounted backdrop while open, Base UI's `modal`.

pub const fn modal(mut self, modal: bool) -> Self

View source

is_modalpub const fn is_modal(&self) -> bool—

Configures is modal for this part.

pub const fn is_modal(&self) -> bool

View source

align_item_with_triggerpub const fn align_item_with_trigger(mut self, align: bool) -> Self—

Open the popup so the selected row overlaps the trigger, Base UI's `alignItemWithTrigger`. QuickGUI offsets the anchored surface by the selected row's distance from the top of the popup plus [`SelectPopoverLayout::trigger_height`], so the row the user is already looking at does not move under the pointer. The native surface still resolves the final side against the display work area.

pub const fn align_item_with_trigger(mut self, align: bool) -> Self

View source

aligns_item_with_triggerpub const fn aligns_item_with_trigger(&self) -> bool—

Configures aligns item with trigger for this part.

pub const fn aligns_item_with_trigger(&self) -> bool

View source

set_pressedpub const fn set_pressed(&mut self, pressed: bool) -> bool—

Record that the trigger is held down, Base UI's `data-pressed`.

pub const fn set_pressed(&mut self, pressed: bool) -> bool

View source

set_focusedpub const fn set_focused(&mut self, focused: bool) -> bool—

Record trigger focus, and mark the control touched when focus leaves it.

pub const fn set_focused(&mut self, focused: bool) -> bool

View source

mark_touchedpub const fn mark_touched(&mut self) -> bool—

Mark the control as having been interacted with, Base UI's `data-touched`.

pub const fn mark_touched(&mut self) -> bool

View source

reset_touchedpub const fn reset_touched(&mut self) -> bool—

Forget that the control was interacted with, for a form that has just been reset. This is the counterpart of [`Self::reset_dirty`]: a value applied from a declaration is not an interaction, so a host that seeds the control reports Base UI's `data-touched` only for what the user really did.

pub const fn reset_touched(&mut self) -> bool

View source

reset_dirtypub const fn reset_dirty(&mut self) -> bool—

Forget that the value changed, for a form that has just been submitted or reset.

pub const fn reset_dirty(&mut self) -> bool

View source

is_dirtypub const fn is_dirty(&self) -> bool—

Configures is dirty for this part.

pub const fn is_dirty(&self) -> bool

View source

is_touchedpub const fn is_touched(&self) -> bool—

Configures is touched for this part.

pub const fn is_touched(&self) -> bool

View source

is_focusedpub const fn is_focused(&self) -> bool—

Configures is focused for this part.

pub const fn is_focused(&self) -> bool

View source

statepub fn state(&self) -> SelectPartState—

A copyable render-state snapshot the application styles from.

pub fn state(&self) -> SelectPartState

View source

selected_itempub fn selected_item(&self) -> Option<&PickerItem<T>>—

Configures selected item for this part.

pub fn selected_item(&self) -> Option<&PickerItem<T>>

View source

selected_valuepub fn selected_value(&self) -> Option<&T>—

Configures selected value for this part.

pub fn selected_value(&self) -> Option<&T>

View source

popover_windowpub const fn popover_window(&self) -> Option<WindowHandle>—

Configures popover window for this part.

pub const fn popover_window(&self) -> Option<WindowHandle>

View source

is_openpub const fn is_open(&self) -> bool—

Configures is open for this part.

pub const fn is_open(&self) -> bool

View source

is_disabledpub const fn is_disabled(&self) -> bool—

Configures is disabled for this part.

pub const fn is_disabled(&self) -> bool

View source

is_invalidpub const fn is_invalid(&self) -> bool—

Configures is invalid for this part.

pub const fn is_invalid(&self) -> bool

View source

set_items

pub fn set_items( &mut self, items: impl IntoIterator<Item = PickerItem<T>>, cx: &mut EventContext, ) -> Result<(), PickerError>

—

Replace the complete bounded source atomically and close an obsolete open snapshot.

pub fn set_items( &mut self, items: impl IntoIterator<Item = PickerItem<T>>, cx: &mut EventContext, ) -> Result<(), PickerError>

View source

select_sourcepub fn select_source(&mut self, source_index: usize) -> bool—

Select one source row. A single select replaces its value. A multiple select adds the row, up to [`MAX_SELECT_VALUES`]. A read-only select refuses both.

pub fn select_source(&mut self, source_index: usize) -> bool

View source

toggle_sourcepub fn toggle_source(&mut self, source_index: usize) -> bool—

Toggle one source row, Base UI's `multiple` item behavior. A single select clears its value when the already-selected row is chosen again; a multiple select removes just that value.

pub fn toggle_source(&mut self, source_index: usize) -> bool

View source

is_source_selectedpub fn is_source_selected(&self, source_index: usize) -> bool—

Whether one source row is currently selected.

pub fn is_source_selected(&self, source_index: usize) -> bool

View source

select_idpub fn select_id(&mut self, id: impl Into<ElementId>) -> bool—

Configures select id for this part.

pub fn select_id(&mut self, id: impl Into<ElementId>) -> bool

View source

clear_selectionpub fn clear_selection(&mut self) -> bool—

Configures clear selection for this part.

pub fn clear_selection(&mut self) -> bool

View source

set_disabledpub fn set_disabled(&mut self, disabled: bool, cx: &mut EventContext) -> bool—

Change disabled state and synchronously request closure of an open native popover.

pub fn set_disabled(&mut self, disabled: bool, cx: &mut EventContext) -> bool

View source

set_invalidpub fn set_invalid(&mut self, invalid: bool) -> bool—

Configures set invalid for this part.

pub fn set_invalid(&mut self, invalid: bool) -> bool

View source

validation_messagepub fn validation_message(&self) -> Option<&Arc<str>>—

Configures validation message for this part.

pub fn validation_message(&self) -> Option<&Arc<str>>

View source

set_validation_messagepub fn set_validation_message(&mut self, message: impl Into<Arc<str>>) -> bool—

Configures set validation message for this part.

pub fn set_validation_message(&mut self, message: impl Into<Arc<str>>) -> bool

View source

clear_validation_messagepub fn clear_validation_message(&mut self) -> bool—

Configures clear validation message for this part.

pub fn clear_validation_message(&mut self) -> bool

View source

closepub fn close(&mut self, cx: &mut EventContext) -> bool—

Configures close for this part.

pub fn close(&mut self, cx: &mut EventContext) -> bool

View source

surface_idpub fn surface_id(id: impl Into<ElementId>) -> ElementId—

Configures surface id for this part.

pub fn surface_id(id: impl Into<ElementId>) -> ElementId

View source

option_id_for_sourcepub fn option_id_for_source( &self, id: impl Into<ElementId>, source_index: usize, ) -> Option<ElementId>—

Configures option id for source for this part.

pub fn option_id_for_source( &self, id: impl Into<ElementId>, source_index: usize, ) -> Option<ElementId>

View source

label_idpub fn label_id(id: impl Into<ElementId>) -> ElementId—

Stable identity of the mounted label part.

pub fn label_id(id: impl Into<ElementId>) -> ElementId

View source

value_idpub fn value_id(id: impl Into<ElementId>) -> ElementId—

Stable identity of the mounted value part.

pub fn value_id(id: impl Into<ElementId>) -> ElementId

View source

icon_idpub fn icon_id(id: impl Into<ElementId>) -> ElementId—

Stable identity of the mounted icon part.

pub fn icon_id(id: impl Into<ElementId>) -> ElementId

View source

backdrop_idpub fn backdrop_id(id: impl Into<ElementId>) -> ElementId—

Stable identity of the optional owner-window backdrop.

pub fn backdrop_id(id: impl Into<ElementId>) -> ElementId

View source

arrow_idpub fn arrow_id(id: impl Into<ElementId>) -> ElementId—

Stable identity of the decorative popup arrow.

pub fn arrow_id(id: impl Into<ElementId>) -> ElementId

View source

list_idpub fn list_id(id: impl Into<ElementId>) -> ElementId—

Stable identity of the scrolling option list inside the popup.

pub fn list_id(id: impl Into<ElementId>) -> ElementId

View source

scroll_up_arrow_idpub fn scroll_up_arrow_id(id: impl Into<ElementId>) -> ElementId—

Stable identity of the upward scroll affordance.

pub fn scroll_up_arrow_id(id: impl Into<ElementId>) -> ElementId

View source

scroll_down_arrow_idpub fn scroll_down_arrow_id(id: impl Into<ElementId>) -> ElementId—

Stable identity of the downward scroll affordance.

pub fn scroll_down_arrow_id(id: impl Into<ElementId>) -> ElementId

View source

`SelectState::root_with`

View source

pub fn root_with(root: Element) -> Element

Decorate the optional application-owned structural wrapper, Base UI's `Select.Root`.

`SelectState::root`

View source

pub fn root() -> Element

Create the unstyled root part. Use [`Self::root_with`] to supply an existing element.

`SelectState::label_with`

View source

pub fn label_with(id: impl Into<ElementId>, label: Element) -> Element

Decorate the caller-owned visible label, Base UI's `Select.Label`. [`Self::trigger_with`] points at this identity, so the label names the control without its text being copied into a second accessible string.

`SelectState::label`

View source

pub fn label(id: impl Into<ElementId>) -> Element

Create the unstyled label part. Use [`Self::label_with`] to supply an existing element.

`SelectState::value_with`

View source

pub fn value_with(id: impl Into<ElementId>, value: Element) -> Element

Decorate the caller-owned value text inside the trigger, Base UI's `Select.Value`. The trigger already exposes the selected value, so this part is hidden from assistive technology and would otherwise be announced twice. Render [`Self::value_text`] inside it, or the placeholder when it returns `None`.

`SelectState::value`

View source

pub fn value(id: impl Into<ElementId>) -> Element

Create the unstyled value part. Use [`Self::value_with`] to supply an existing element.

`SelectState::icon_with`

View source

pub fn icon_with(id: impl Into<ElementId>, icon: Element) -> Element

Decorate the caller-owned trigger affordance, Base UI's `Select.Icon`.

`SelectState::icon`

View source

pub fn icon(id: impl Into<ElementId>) -> Element

Create the unstyled icon part. Use [`Self::icon_with`] to supply an existing element.

`SelectState::backdrop_with`

View source

pub fn backdrop_with(id: impl Into<ElementId>, backdrop: Element) -> Element

Decorate an optional caller-painted owner-window backdrop, Base UI's `Select.Backdrop`. The option surface is a separate native child window that already takes the pointer grab, so this layer exists only for a caller-painted dimming pass. Mount it while [`Self::is_open`] is true, and declare [`Self::modal`] so the intent is inspectable.

`SelectState::backdrop`

View source

pub fn backdrop(id: impl Into<ElementId>) -> Element

Create the unstyled backdrop part. Use [`Self::backdrop_with`] to supply an existing element.

`SelectState::portal_with`

View source

pub fn portal_with( id: impl Into<ElementId>, label: impl Into<Arc<str>>, option_count: usize, multiple: bool, portal: Element, ) -> Element

Decorate the popup boundary, Base UI's `Select.Portal` and `Select.Positioner`. QuickGUI's option surface is its own native window, so the portal, the positioner, and the popup are one element: all three names decorate it identically and QuickGUI resolves its placement against the display work area rather than a parent stacking context.

`SelectState::portal`

View source

pub fn portal( id: impl Into<ElementId>, label: impl Into<Arc<str>>, option_count: usize, multiple: bool, ) -> Element

Create the unstyled portal part. Use [`Self::portal_with`] to supply an existing element.

`SelectState::positioner_with`

View source

pub fn positioner_with( id: impl Into<ElementId>, label: impl Into<Arc<str>>, option_count: usize, multiple: bool, positioner: Element, ) -> Element

Decorate the popup boundary, Base UI's `Select.Positioner`.

`SelectState::positioner`

View source

pub fn positioner( id: impl Into<ElementId>, label: impl Into<Arc<str>>, option_count: usize, multiple: bool, ) -> Element

Create the unstyled positioner part. Use [`Self::positioner_with`] to supply an existing element.

`SelectState::popup_with`

View source

pub fn popup_with( id: impl Into<ElementId>, label: impl Into<Arc<str>>, option_count: usize, multiple: bool, popup: Element, ) -> Element

Decorate the caller-owned option surface, Base UI's `Select.Popup`. QuickGUI applies this to whatever the surface renderer returns, so an application that composes its own in-window list can reuse exactly the semantics the native surface gets.

`SelectState::popup`

View source

pub fn popup( id: impl Into<ElementId>, label: impl Into<Arc<str>>, option_count: usize, multiple: bool, ) -> Element

Create the unstyled popup part. Use [`Self::popup_with`] to supply an existing element.

`SelectState::arrow_with`

View source

pub fn arrow_with(id: impl Into<ElementId>, arrow: Element) -> Element

Position a caller-owned decorative arrow, Base UI's `Select.Arrow`.

`SelectState::arrow`

View source

pub fn arrow(id: impl Into<ElementId>) -> Element

Create the unstyled arrow part. Use [`Self::arrow_with`] to supply an existing element.

`SelectState::list_with`

View source

pub fn list_with(id: impl Into<ElementId>, option_count: usize, list: Element) -> Element

Decorate the caller-owned scrolling option list, Base UI's `Select.List`. The popup already carries the list-box role, so the inner list is a structural container: it keeps a stable identity and the declared set size without announcing a second list.

`SelectState::list`

View source

pub fn list(id: impl Into<ElementId>, option_count: usize) -> Element

Create the unstyled list part. Use [`Self::list_with`] to supply an existing element.

`SelectState::item_with`

View source

pub fn item_with( row_id: impl Into<ElementId>, label: impl Into<Arc<str>>, state: SelectOptionState, row: Element, ) -> Element

Decorate one caller-owned option row, Base UI's `Select.Item`. `row_id` comes from [`Self::option_id_for_source`], so the row keeps the identity the popup's active-descendant relationship points at.

`SelectState::item`

View source

pub fn item( row_id: impl Into<ElementId>, label: impl Into<Arc<str>>, state: SelectOptionState, ) -> Element

Create the unstyled item part. Use [`Self::item_with`] to supply an existing element.

`SelectState::item_text_with`

View source

pub fn item_text_with(text: Element) -> Element

Decorate one option's visible text, Base UI's `Select.ItemText`. The row already carries the accessible name, so the text is decoration.

`SelectState::item_text`

View source

pub fn item_text() -> Element

Create the unstyled item text part. Use [`Self::item_text_with`] to supply an existing element.

`SelectState::item_indicator_with`

View source

pub fn item_indicator_with(indicator: Element) -> Element

Decorate one option's selected mark, Base UI's `Select.ItemIndicator`. The row already reports selection, so the indicator is hidden from assistive technology. Mount it only while the row is selected, exactly as Base UI does.

`SelectState::item_indicator`

View source

pub fn item_indicator() -> Element

Create the unstyled item indicator part. Use [`Self::item_indicator_with`] to supply an existing element.

`SelectState::group_with`

View source

pub fn group_with(group: Element) -> Element

Decorate a caller-composed option group, Base UI's `Select.Group`.

`SelectState::group`

View source

pub fn group() -> Element

Create the unstyled group part. Use [`Self::group_with`] to supply an existing element.

`SelectState::group_label_with`

View source

pub fn group_label_with(label_id: impl Into<ElementId>, label: Element) -> Element

Decorate a group's visible label, Base UI's `Select.GroupLabel`. Pass the same `label_id` to [`Element::accessibility_labelled_by`] on the group so the two are related without the text being copied.

`SelectState::group_label`

View source

pub fn group_label(label_id: impl Into<ElementId>) -> Element

Create the unstyled group label part. Use [`Self::group_label_with`] to supply an existing element.

`SelectState::separator_with`

View source

pub fn separator_with(separator: Element) -> Element

Decorate a caller-owned divider between option groups, Base UI's `Select.Separator`.

`SelectState::separator`

View source

pub fn separator() -> Element

Create the unstyled separator part. Use [`Self::separator_with`] to supply an existing element.

`SelectState::trigger_with`

View source

pub fn trigger_with( &self, id: impl Into<ElementId>, label: impl Into<Arc<str>>, trigger: Element, ) -> Element

Decorate an application-owned trigger without adding appearance, Base UI's `Select.Trigger`.

`SelectState::trigger`

View source

pub fn trigger(&self, id: impl Into<ElementId>, label: impl Into<Arc<str>>) -> Element

Create the unstyled trigger part. Use [`Self::trigger_with`] to supply an existing element.

`SelectState::element`

View source

pub fn element<V, PopoverRoot, RenderOption, Change>( &self, cx: &mut ViewContext<'_, V>, id: impl Into<ElementId>, label: impl Into<Arc<str>>, access: fn(&mut V) -> &mut SelectState<T>, trigger: Element, popover_root: PopoverRoot, render_option: RenderOption, change: Change, ) -> Element where V: 'static, T: Clone + 'static, PopoverRoot: Fn(SelectListState) -> Element + Clone + 'static, RenderOption: Fn(&PickerItem<T>, SelectOptionState) -> Element + Clone + 'static, Change: Fn(&mut V, T, &mut EventContext) + Clone + 'static,

Build the complete unstyled select interaction from caller-owned trigger, popover, and rows. This is the `fn`-pointer entry point: a view that owns one select per field passes `Self::field`. A host that renders many declared selects through one view passes a per-instance [`StateAccessor`] to [`SelectState::element_with`] instead.

`SelectState::element_with`

View source

pub fn element_with<V, PopoverRoot, RenderOption, Change>( &self, cx: &mut ViewContext<'_, V>, id: impl Into<ElementId>, label: impl Into<Arc<str>>, access: StateAccessor<V, SelectState<T>>, trigger: Element, popover_root: PopoverRoot, render_option: RenderOption, change: Change, ) -> Element where V: 'static, T: Clone + 'static, PopoverRoot: Fn(SelectListState) -> Element + Clone + 'static, RenderOption: Fn(&PickerItem<T>, SelectOptionState) -> Element + Clone + 'static, Change: Fn(&mut V, T, &mut EventContext) + Clone + 'static,

Build the select interaction against a per-instance retained-state accessor. Two selects declared by one view stay independent because the accessor, not the view type, decides which [`SelectState`] each registered listener resolves.

`SelectState::element_with_trigger`

View source

pub fn element_with_trigger<V, PopoverRoot, RenderOption, Change>( &self, cx: &mut ViewContext<'_, V>, id: impl Into<ElementId>, label: impl Into<Arc<str>>, access: fn(&mut V) -> &mut SelectState<T>, trigger: Element, popover_root: PopoverRoot, render_option: RenderOption, change: Change, ) -> Element where V: 'static, T: Clone + 'static, PopoverRoot: Fn(SelectListState, &SelectPopupParts<'_>) -> Element + Clone + 'static, RenderOption: Fn(&PickerItem<T>, SelectOptionState) -> Element + Clone + 'static, Change: Fn(&mut V, T, &mut EventContext) + Clone + 'static,

Build the select interaction with access to the framework-owned popup parts. The surface renderer additionally receives [`SelectPopupParts`], whose `scroll_up_arrow_with` and `scroll_down_arrow_with` decorators carry Base UI's hovered scrolling behavior. Every other entry point is this one with a renderer that ignores them.

`SelectState::element_with_trigger_accessor`

View source

pub fn element_with_trigger_accessor<V, PopoverRoot, RenderOption, Change>( &self, cx: &mut ViewContext<'_, V>, id: impl Into<ElementId>, label: impl Into<Arc<str>>, access: StateAccessor<V, SelectState<T>>, trigger: Element, popover_root: PopoverRoot, render_option: RenderOption, change: Change, ) -> Element where V: 'static, T: Clone + 'static, PopoverRoot: Fn(SelectListState, &SelectPopupParts<'_>) -> Element + Clone + 'static, RenderOption: Fn(&PickerItem<T>, SelectOptionState) -> Element + Clone + 'static, Change: Fn(&mut V, T, &mut EventContext) + Clone + 'static,

Build the popup-parts select interaction against a per-instance retained-state accessor.