BaseSelect
Compose a custom listbox with selection, navigation, and popup ownership.
Anatomy#
Control is an optional layout container and floating anchor; without it, Content anchors to the registered focus owner.
Usage#
Use BaseSelect to build a custom selection control from a trigger and listbox parts. It manages selected values, open state, keyboard navigation, and native form values. Your application owns filtering, query text, grouping, and item creation.
For a ready-made field, start with Select, Combobox, or MultiSelect.
Values and form submission#
value, defaultValue, and onValueChange always use arrays, even for single selection; without
multiple, only the first entry is used. value={undefined} keeps the selection uncontrolled and
value={[]} keeps it controlled and empty. Choosing an item closes the popup unless you set
multiple or closeOnSelect={false}. Set name to submit the selection with the enclosing native
form; use serializeValue to change or omit a submitted value.
Control and focus ownership#
Control is an optional, non-interactive layout container and floating anchor. It does not toggle,
own keyboard navigation, become a tab stop, or receive role="combobox". Trigger is the primary
select-like focus owner and activator. If Control is omitted, Content anchors to the registered
focus owner.
For an editable composition, bind your own <input> with createBaseSelectSearchInput from
moraine/utils. Call it in a component rendered inside BaseSelect, passing BaseSelect.useContext()
as state, and spread inputProps on the input. The helper registers the input as the focus owner
and adds the combobox ARIA attributes and keyboard handling. It does not make the input the floating
anchor, so render a BaseSelect.Control around it. You own the input, the canonical source,
filtering, and query reset. No BaseSelect.Trigger is required in that pattern.
Item fields#
BaseSelect.Item takes the collection entry through the item prop: <BaseSelect.Item item={item} />.
Other props are DOM and rendering props for the rendered <div>. Custom item fields are available
through render state, and arbitrary item fields never leak into DOM attributes:
<BaseSelect.Item<MyItem> item={item}>{(state) => state.item.custom}</BaseSelect.Item>.
Without children, Item renders item.label.
Filtered collections#
items is the flat list of every item you render as BaseSelect.Item; an item whose value is not
in items cannot be selected. By default, items is both the canonical data source and the active
navigation collection. Values must be unique. Groups and separators are rendering concerns and do
not belong in items.
For custom filtered compositions such as searchable controls, provide getItemByValue alongside
a filtered items view:
The filtered items array controls which options users can navigate. getItemByValue looks up
selected items in the full collection, so labels, disabled state, and form values remain available
when an item is filtered out.
Styling#
BaseSelect exposes the style slots control, trigger, content, listbox, item, group,
groupLabel, separator, and empty through classes and styles on the root. Each part also
accepts class and style for its own element. See Customization and
Theming for nested Provider, Portal, and class-merging behavior.
Examples#
Pick a grouped framework#
Compose groups, group labels, and item render state when Select’s built-in collection is not enough. Resolve the trigger label from the full collection.
Search a custom listbox#
Own the query and the filtered items, and bind the input with createBaseSelectSearchInput. Pass
getItemByValue so a selected option still resolves after it leaves the filtered view.
Select multiple frameworks#
Set multiple and read state.value as an array. Summarize the whole selection in the trigger
instead of showing a single label. The popup stays open after each choice.
Submit a native form value#
Give the root a name. BaseSelect writes the selected value into the enclosing native form without
createForm.
API Reference#
Attributes#
data-closeddata-disableddata-expandeddata-invaliddata-readonlydata-requireddata-sidedata-highlighteddata-selectedProps#
BaseSelect#
Control#
Renders a <div> element by default.
Trigger#
Renders a <button> element by default.
Content#
Renders a <div> element by default.
Listbox#
Renders a <div> element by default.
Item#
Renders a <div> element by default.
Group#
Renders a <div> element by default.
GroupLabel#
Renders a <div> element by default.
Separator#
Renders a <div> element by default.
Empty#
Renders a <div> element by default.