Select

Usage

• Use Select for choosing from a predefined list of options longer than a few items.
• Use Checkbox Groups for selecting one or more options from a short list.
• Use Radio Groups for short lists where only one option may be selected with a possible default.
• Use Segmented Controls for 2–3 mutually exclusive options that toggle frequently.
• Use Text Fields for freeform text input.
• Enable search (isSearchable) for lists longer than 10 items.
• Enable virtualization (withVirtualizer) for large lists to prevent performance issues.
• Provide a visible label so users understand the purpose of the field at a glance.
• Add a description to disabled options explaining why they are unavailable.

Types

• Single-select — the default mode; allows one selection from the list.
• Multi-select (isMulti) — allows one or more selections; selected values display as removable tags.
• Searchable (isSearchable) — adds a text input inside the dropdown for filtering options.
• Creatable (withCreate + isSearchable) — allows users to create new options when the search input does not match an existing option. Best for tags or custom attributes.

Appearance

• Medium (size="md") — default size for most use cases.
• Small (size="sm") — use for compact layouts and less prominent lists.
• Add an icon to options to provide visual context such as categories or avatars.
• Add a description to options when labels alone do not convey the purpose of each choice.
• Use iconComponent to render custom icons (avatars, status indicators) in place of the default icon.
• Use optionComponent to render custom option content with metadata, status indicators, or additional layout.
• Use valueComponent to customize how the selected value displays in the trigger.
• Use headerComponent or beforeOptionsComponent to add context above the option list in the dropdown.
• Use footerComponent to add supplementary actions or context below the option list.
• Wrap multi-select tags to additional lines (canWrap) when truncation would hide important selections.

Behaviors

• Base, hover, focus, active — standard form control interaction states.
• Disabled state (isDisabled) — prevents all interaction; field and text adopt disabled styling.
• Loading state (isLoading) — displays a spinner icon indicating options are being loaded.
• Danger state (isInvalid + error) — applies danger styling and displays error text below the field.
• Clearable fields (isClearable) — adds a clear button to reset the field after a selection is made. Use for optional Selects.
• Group options to organize longer lists into digestible categories. Avoid grouping short lists.
• Make groups collapsible (isCollapsible on a group) to let users expand and collapse sections. Use defaultIsCollapsed to start a group collapsed.
• Add tooltip to options to surface additional detail on hover or focus without inline descriptions.

Content

• Write clear, concise labels using nouns or noun phrases. Never use instructional phrases as labels.
• Keep option labels to a few words. Use sentence case. Add a description or tooltip if more context is needed.
• Use placeholder text in the format "Select a [noun]" or "Search [noun]" when search is enabled.
• Never use vague placeholders like "Select..." or "Type to search...".
• Never use placeholders in place of visible labels.
• Write description text as complete, short sentences that provide hints or constraints — never repeat the label.
• Write error messages that state the specific problem and how to fix it.

Implementation Notes

• Provide options as an array of { value, label } objects. Options also accept optional description, icon, tooltip, isDisabled, and searchLabel fields.
• Group options by nesting them: { label: 'Group name', options: [...] }. Groups accept isCollapsible, defaultIsCollapsed, icon, isDisabled, and tooltip.
• Single-select value is a string or option object; onChange receives string | null. Multi-select value is an array; onChange receives string[] | null.
• isClearable calls onChange(null) when cleared — there is no separate onClear callback.
• withCreate requires isSearchable to function. Creating a new option calls onCreate(value), not onChange. The consumer must update both options and value inside the onCreate callback.
• canCreateNewOption accepts a function to exclude certain values from showing the "Create new" option. createOptionLabel customizes the create option text.
• canWrap only applies when isMulti is true.
• Control the dropdown programmatically with isOpen, defaultIsOpen, and onOpenChange.
• Use onLoadMore, shouldLoadMore, and isLoadingMore for paginated/infinite-scroll loading.
• Use searchInputValue and onSearchInput together to control filtering externally (the component will not filter on its own when these are provided).
• unsafe_popoverClassName, unsafe_popoverStyle, and unsafe_popoverSize customize the floating dropdown element.
• unsafe_initialSearchValue pre-fills the search input (intended for snapshots/tests only).
• In Ember, use <PlumaSelect> with @argName syntax. Named blocks {{:label}}, {{:description}}, and {{:error}} allow custom rich content for those slots.
• In React, label, description, and error accept ReactNode for rich content directly as props.