Select

Single or multiple selection with array options, controlled values and shared field presentation.

Reading direction

Select inherits source dir. Standalone fields align to inline start; FormItem content-align still takes precedence when inherited. Explicit left/right alignment remains physical. Tags keep their array order and empty-search Backspace removes the last closable value. Dropdowns and picker panels retain source direction, including in a custom popup-container.

Async arrays and clearing

useAsyncData is a public composable exported by @cedar-design/use. Pass a loader to that composable and bind its data/loading to Select. Options remain arrays. An initialization call is per owner; share a parent result to avoid duplicate loading.

empty-value sets the single-selection clear result. Omitted preserves the existing behavior: empty string unless an empty-string option exists, in which case clearing may produce undefined. The event types include undefined. Multiple selection keeps its array semantics and cannot clear disabled selected options.

case-sensitive defaults to false. search-fields defaults to ['label']; ['value', 'label'] matches either field. Custom filters retain priority.

Variable	Default
--c-select-popup-option-check-color	var(--c-sys-color-action-primary)
--c-select-popup-option-check-size	var(--c-sys-font-size-md)
--c-select-popup-option-check-gap	var(--c-sys-space-4)

Basic examples

Basic

Appearance and states

Appearance configuration comparison

Configuration reference for this comparison

Configuration	Purpose	Related examples
options	Primitive, object or grouped options; one source for every presentation	Appearance configuration comparison, Control Sizes
clearable	Allow clearing; preserve disabled selections	Appearance configuration comparison, Control Sizes
size	Supports all five sizes; inherits group/form settings	Control Sizes
variant	filled, outline, standard; inherits InputGroup	Control Sizes
placeholder	Placeholder	Control Sizes
multiple	Multiple selection; enables search by default	Control Sizes

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Control Sizes

Selection modes and options

Multiple

Configuration reference for this comparison

Configuration	Purpose	Related examples
placeholder	Placeholder	Multiple, Same Label, Optgroup
multiple	Multiple selection; enables search by default	Multiple, Same Label, Optgroup
clearable	Allow clearing; preserve disabled selections	Multiple, Same Label, Options Review
filterable	Enable search; optionally retainInputValue	Same Label, Options Review
options	Primitive, object or grouped options; one source for every presentation	Same Label, Group Spacing
scrollbar	Whether to enable virtual scroll bar	Multiple

Same Label

Optgroup

Group Spacing

Options Review

Allow Create

Fallback Option

Search and filtering

Filterable

Configuration reference for this comparison

Configuration	Purpose	Related examples
placeholder	Placeholder	Filterable, Search Matching, Dropdown Scroll
options	Primitive, object or grouped options; one source for every presentation	Filterable, Search Matching, Virtual List
filterable	Enable search; optionally retainInputValue	Filterable, Search Matching
loading	Loading state; blocks selection and confirmation	Filterable
multiple	Multiple selection; enables search by default	Filterable
case-sensitive	Case-sensitive built-in filtering; custom filters take priority	Search Matching

Search Matching

Dropdown Scroll

Virtual List

Content and dropdown customization

Tag Props

Configuration reference for this comparison

Configuration	Purpose	Related examples
placeholder	Placeholder	Tag Props, Custom Header, Custom Footer
multiple	Multiple selection; enables search by default	Tag Props, Custom Header, Slots Review
options	Primitive, object or grouped options; one source for every presentation	Tag Props, Slots Review
filterable	Enable search; optionally retainInputValue	Custom Footer, Slots Review
clearable	Allow clearing; preserve disabled selections	Slots Review

Custom Header

Custom Footer

Custom Label

Slots Review

Value model and linked fields

Selection Data Flow

Configuration reference for this comparison

Configuration	Purpose	Related examples
options	Primitive, object or grouped options; one source for every presentation	Selection Data Flow, Linkage, Empty recognition and clear output
clearable	Allow clearing; preserve disabled selections	Empty recognition and clear output, Interaction state comparison
edit-mode	Field presentation; inherits FormItem/Form when omitted	Selection Data Flow
default-active-first-option	On opening, activate the first enabled candidate if no valid selected option exists. Highlighting does not update modelValue or emit change; an existing valid selection takes priority	Selection Data Flow
placeholder	Placeholder	Selection Data Flow
empty-value	Clear output override; return an array for multiple selection and preserve protected items	Empty recognition and clear output

Linkage

Empty recognition and clear output

This example keeps an empty string as the valid All option and clears to null. Compare the selected All option with the cleared state in the model output. Deleting the search query does not remove the selected value. The additional fields show multiple selection clearing to [] and a factory explicitly producing undefined, each with its own model output.

Interaction state comparison

Toggle disabled, read-only and error states, then interact with the same instance. Recovery controls remain outside the target; error appearance alone does not validate data.

Async data and search

Loading

Configuration reference for this comparison

Configuration	Purpose	Related examples
loading	Loading state; blocks selection and confirmation	Loading, Search, Async Devices
options	Primitive, object or grouped options; one source for every presentation	Search, Async Devices, Async Source
placeholder	Placeholder	Loading, Search, Async Devices
filterable	Enable search; optionally retainInputValue	Async Devices, Async Source, Async Data
multiple	Multiple selection; enables search by default	Search, Async Devices
filter-option	false disables local filtering; callback receives query and raw option	Search

Search

Async Devices

Async Source

Async Data

Configuration and lifecycle

Passthrough Options

Configuration reference for this comparison

Configuration	Purpose	Related examples
options	Primitive, object or grouped options; one source for every presentation	Passthrough Options, Scheduler Lifecycle, Copying and editing
edit-mode	Field presentation; inherits FormItem/Form when omitted	Passthrough Options, Copying and editing
trigger-props	Optional dropdown Trigger settings. Placement defaults to bottom-start and automatically adjusts when space is limited. The field owns open state; there is no top-level placement prop	Passthrough Options
open-trigger-target	Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available.	Copying and editing
filterable	Enable search; optionally retainInputValue	Copying and editing

Select

Prop	Description	Type	Default
open-trigger-target	Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available.	'field' | 'icon'	'field'
model-value / default-value	Controlled value / uncontrolled initial value	Value	Single: ''; multiple: []
open / default-open	Controlled / initial open state	boolean	undefined / false
input-value / default-input-value	Search text, independent of selected values	string	undefined / ''
multiple	Multiple selection; enables search by default	boolean	false
size	Supports all five sizes; inherits group/form settings	ComponentSize	md
variant	filled, outline, standard; inherits InputGroup	FormControlVariant	filled
disabled / readonly / error	Inherits form state unless explicitly overridden	boolean	undefined
placeholder	Placeholder	string	—
hint / line	Floating hint / standard variant underline	boolean	true
text-color / focus-color / blur-color	Field colors	string	—
loading	Loading state; blocks selection and confirmation	boolean	false
show-tags	Show tags; false displays separated text	boolean	true
separator	Separator when show-tags=false	string	,
text-align	Value alignment: left / center / right. Inherits FormItem content-align when omitted; defaults to inline start outside forms.	'left' | 'center' | 'right'	-
max-tag-count	Maximum visible tags; 0 means unlimited	number	0
tag-nowrap	Keep tags on one line with ellipsis and preserved removal icons; overflow scrolls horizontally; hover, focus or tap truncated text to preview it	boolean	false
popup-container	Selector, element, element resolver, or false for inline rendering	PopupContainer	—
trigger-props	Optional dropdown Trigger settings. Placement defaults to bottom-start and automatically adjusts when space is limited. The field owns open state; there is no top-level placement prop	TriggerProps	—
virtual-list-props	Pass the virtual list attribute, pass in this parameter to turn on virtual scrolling VirtualListProps	VirtualListProps	—
search-delay	Search debounce delay in ms	number	500
format-label	Format selected labels; use label slot for VNodes	function	—
clearable	Allow clearing; preserve disabled selections	boolean	true
empty-value	Clear output override; return an array for multiple selection and preserve protected items	SelectEmptyValue	undefined
options	Primitive, object or grouped options; one source for every presentation	SelectOption[] / (query, { signal }) => Array / Promise	undefined
field-names	Map value, label, disabled, tagProps, render; object values need a unique ID field	SelectFieldNames	—
filterable	Enable search; optionally retainInputValue	boolean or { retainInputValue?: boolean }	Single: false / multiple: true
case-sensitive	Case-sensitive built-in filtering; custom filters take priority	boolean	false
filter-option	false disables local filtering; callback receives query and raw option	boolean or (input, option) => boolean	automatic: arrays on; loader off
creatable	Allow creating missing options	boolean	false
fallback-option	Display unresolved values or return a complete fallback option	boolean or (value) => SelectOptionData	true
show-extra-options	Display fallback/created options in the panel	boolean	true
limit	Selection limit; 0 means unlimited	number	0
auto-fit-popup-width	Match Menu width to the field	boolean	true
default-active-first-option	On opening, activate the first enabled candidate if no valid selected option exists. Highlighting does not update modelValue or emit change; an existing valid selection takes priority	boolean	true
unmount-on-close	Unmount Menu content when closed	boolean	false
scrollbar	Whether to enable virtual scroll bar	boolean or ScrollbarProps	true
show-header-on-empty / show-footer-on-empty	Display header/footer in empty state	boolean	false
edit-mode	Field presentation; inherits FormItem/Form when omitted	direct / click / dblclick	direct
before-commit	Asynchronous before-commit hook after validation	(value, context) => void / false / Promise	—

Option Props

Prop	Description	Type	Default
value	Option Value	string | number | boolean | Record<string, unknown>	undefined
label	Option group title	string	undefined
disabled	Whether to disable	boolean	false
tag-props	Props of the multi-select label corresponding to the option	TagProps	undefined
index	Explicit option order	number	undefined

Option Slots

Slot	Description	Arguments
default	Custom option content	{ selected: boolean }
icon	Option icon	-
suffix	Option suffix	-

Optgroup Props

Prop	Description	Type	Default
label	Option group title	string	undefined

Optgroup Slots

Slot	Description	Arguments
label	Option group title	-
default	Option children in this group	-

Select Slots

Slot	Description	Arguments
default	Option or Optgroup children	-
option	Custom option content	{ data }
label	Option group title	{ data }
selected	Replace the whole selected-value region	-
header	Menu header	-
footer	Menu footer	-
trigger	Custom field trigger	-
prefix	Field prefix	-
suffix	Field suffix	-
clear-icon	Custom clear action	{ clear }
arrow-icon	Dropdown arrow	-
search-icon	Search icon	-
loading-icon	Loading icon	-
empty	Empty-state content	-
read	Read-mode content	{ value, text }

Select Events

Event	Description	Arguments
update:model-value	Request a model value update	value
change	Option	value
update:open	Request popup visibility	open
open-change	Popup visibility changes	open
update:input-value	Request search text update	text
input-value-change	Search text changes	text
search	Triggered when the user searches	text
focus	Focus enters the field	event
blur	Focus leaves the field	event
clear	Triggered when the value of the input changes	event
remove	Triggered when the delete button of the label is clicked	value
exceed-limit	Selection would exceed the multiple-selection limit	value, event
dropdown-scroll	Menu scrolls	event
dropdown-reach-bottom	Menu reaches its bottom	event

Select Methods

Method	Description	Arguments
focus	Focus the actual field	-
blur	Blur the actual field	-

Scheduler Lifecycle

Api Review

Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Shared field loading

loading displays the shared field indicator. loading-mode is default (indicator) or line (an indeterminate bottom line); it defaults to default. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

API

Empty values and reading placeholders

empty-values recognizes empty data; empty-value keeps existing clear output. empty-text defaults to '-' under read-pretty, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the shared guide.

Prop	Type	Default and scope
empty-values	readonly unknown[]	Field > FormItem > Form > component-family default; replaces the whole list
empty-text	string	Field > FormItem > Form > '-'; explicit '' is valid

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

Selected rows show a primary-colored right-side checkmark in both single/multiple modes; candidate highlighting alone does not. In click/dblclick editors, checkmarks reflect draft selection, committed to Form only on confirmation. Disabled selected items retain disabled appearance.

Cleared values and 1.x compatibility

SelectValue includes undefined. By default, single-select clear emits ''; if the current options contain a value: '' option, it emits undefined to distinguish clearing from selecting that option. This published behavior is preserved. Both change and update:modelValue use SelectValue.

empty-value defines clear output; omission preserves the existing fallback. Single selection can use () => undefined to explicitly return undefined; multiple selection should return an array matching its model shape. Protected disabled selections take priority and prevent the clear override from running. Controlled mode still requires parent acceptance.

Root and component entries export SelectValue and SelectEmptyValue.

Select props

Use v-model, v-model:open and v-model:input-value for controlled state. Clear values are '' for single selection and [] for multiple selection. Select uses undefined when an actual empty-string option exists.

Prop	Description	Type	Default
open-trigger-target	Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available.	'field' | 'icon'	'field'
model-value / default-value	Controlled value / uncontrolled initial value	Value	Single: ''; multiple: []
open / default-open	Controlled / initial open state	boolean	undefined / false
input-value / default-input-value	Search text, independent of selected values	string	undefined / ''
multiple	Multiple selection; enables search by default	boolean	false
size	Supports all five sizes; inherits group/form settings	ComponentSize	md
variant	filled, outline, standard; inherits InputGroup	FormControlVariant	filled
disabled / readonly / error	Inherits form state unless explicitly overridden	boolean	undefined
placeholder	Placeholder	string	—
hint / line	Floating hint / standard variant underline	boolean	true
text-color / focus-color / blur-color	Field colors	string	—
loading	Loading state; blocks selection and confirmation	boolean	false
loading-mode	Loading layout: default indicator or bottom line	default / line	default
show-tags	Show tags; false displays separated text	boolean	true
separator	Separator when show-tags=false	string	,
text-align	Text alignment: left / center / right. Inherits FormItem content-align when unset; standalone fields default to inline start	'left' | 'center' | 'right'	-
max-tag-count	Maximum visible tags; 0 means unlimited	number	0
tag-nowrap	Keep tags on one line with ellipsis and preserved removal icons; overflow scrolls horizontally; hover, focus or tap truncated text to preview it	boolean	false
popup-container	Selector, element, element resolver, or false for inline rendering	PopupContainer	—
trigger-props	Optional dropdown Trigger settings. Placement defaults to bottom-start and automatically adjusts when space is limited. The field owns open state; there is no top-level placement prop	TriggerProps	—
virtual-list-props	Pass the virtual list attribute, pass in this parameter to turn on virtual scrolling VirtualListProps	VirtualListProps	—
search-delay	Search debounce delay in ms	number	500
format-label	Format selected labels; use label slot for VNodes	function	—
clearable	Allow clearing; preserve disabled selections	boolean	true
empty-value	Clear output override; return an array for multiple selection and preserve protected items	SelectEmptyValue	undefined
options	Primitive, object or grouped options; one source for every presentation	SelectOption[] / (query, { signal }) => Array / Promise	undefined
field-names	Map value, label, disabled, tagProps, render; object values need a unique ID field	SelectFieldNames	—
filterable	Enable search; optionally retainInputValue	boolean or { retainInputValue?: boolean }	Single: false; multiple: true
case-sensitive	Case-sensitive built-in filtering; custom filters take priority	boolean	false
filter-option	false disables local filtering; callback receives query and raw option	boolean or (input, option) => boolean	Automatic: enabled for arrays, disabled for loader functions
creatable	Allow creating missing options	boolean	false
fallback-option	Display unresolved values or return a complete fallback option	boolean or (value) => SelectOptionData	true
show-extra-options	Display fallback/created options in the panel	boolean	true
limit	Selection limit; 0 means unlimited	number	0
auto-fit-popup-width	Match Menu width to the field	boolean	true
default-active-first-option	On opening, activate the first enabled candidate if no valid selected option exists. Highlighting does not update modelValue or emit change; an existing valid selection takes priority	boolean	true
unmount-on-close	Unmount Menu content when closed	boolean	false
scrollbar	Whether to enable virtual scroll bar	boolean or ScrollbarProps	true
show-header-on-empty / show-footer-on-empty	Display header/footer in empty state	boolean	false
edit-mode	Field presentation; inherits FormItem/Form when omitted	direct / click / dblclick	direct
before-commit	Asynchronous before-commit hook after validation	(value, context) => void / false / Promise	—

Events and methods

• update:modelValue, change(value): emitted on commit, not while editing a draft.
• update:open, open-change(open): request an expanded-state change.
• update:inputValue, input-value-change(text), search(text): search state.
• focus(event), blur(event), clear(event): native field events; only the field owner notifies Form.
• Methods: focus(), blur().

Select also emits remove(value), exceed-limit(value, event), dropdown-scroll(event), and dropdown-reach-bottom(event).

Slots and option data

Use label({ data }) for custom selected labels; selected replaces the whole selection area. Also supports prefix, suffix, clear-icon({ clear }), arrow-icon, loading-icon, search-icon, empty, and option({ data }).

Option label is searchable plain text. Use render or the option slot for custom option content, and format-label or label slot for selected content. Values identify selections; labels never do. disabled blocks selection/removal, and tagProps customizes selected tags.

Select additionally supports header, footer, trigger, and default Option / Optgroup children. Option props: value, label, disabled, tagProps, index; its default slot receives selected. Group data uses { isGroup: true, label, options }. List and Picker also accept slot options; Picker displays their text labels.

Single/multiple options both use popup-option-padding-horizontal. There is no implicit search-highlight DOM; custom option slots style their own highlighted fragments. Unused multi-popup-option-padding-horizontal and popup-option-highlight-* variables are removed.

read-pretty is an independent boolean alongside readonly and disabled. It inherits from field to FormItem to Form; explicit false overrides the parent. The default is false. Reading mode renders no editor.

Option Props

Prop	Description	Type	Default
value	Option Value	string | number | boolean | Record<string, unknown>	undefined
label	Option group title	string	undefined
disabled	Whether to disable	boolean	false
tag-props	Props of the multi-select label corresponding to the option	TagProps	undefined
index	Explicit option order	number	undefined

Option Slots

Slot	Description	Arguments
default	Custom option content	{ selected: boolean }
icon	Option icon	-
suffix	Option suffix	-

Optgroup Props

Prop	Description	Type	Default
label	Option group title	string	undefined

Optgroup Slots

Slot	Description	Arguments
label	Option group title	-
default	Option children inside a group	-

Select Slots

Slot	Description	Arguments
default	Option / Optgroup children	-
option	Custom option content	{ data }
label	Option group title	{ data }
selected	Replace the whole selected-value region	-
header	Menu header	-
footer	Menu footer	-
trigger	Custom field trigger	-
prefix	Field prefix	-
suffix	Field suffix	-
clear-icon	Custom clear action	{ clear }
arrow-icon	Dropdown arrow	-
search-icon	Search icon	-
loading-icon	Loading icon	-
empty	Empty-state content	-
read	Read-mode content	{ value, text }

Select Events

Event	Description	Arguments
update:model-value	Request a model value update	value
change	Option	value
update:open	Request popup visibility	open
open-change	Popup visibility changes	open
update:input-value	Request search text update	text
input-value-change	Search text changes	text
search	Triggered when the user searches	text
focus	Field gains focus	event
blur	Field loses focus	event
clear	Triggered when the value of the input changes	event
remove	Triggered when the delete button of the label is clicked	value
exceed-limit	Selection would exceed the multiple-selection limit	value, event
dropdown-scroll	Menu scrolls	event
dropdown-reach-bottom	Menu reaches its bottom	event

Select Methods

Method	Description	Arguments
focus	Focus the actual field	-
blur	Blur the actual field	-

Selected-checkmark style variables

Variable	Default
--c-select-popup-option-check-color	var(--c-sys-color-action-primary)
--c-select-popup-option-check-size	var(--c-sys-font-size-md)
--c-select-popup-option-check-gap	var(--c-sys-space-4)

Public type exports

Root and component entries export SelectEmits、SelectSlots、SelectExpose alongside Props and Instance. Emits are event argument tuples derived from the runtime validators; Expose contains focus/blur.

Built-in search fields

searchFields / search-fields is a readonly ('label' | 'value')[], defaulting to ['label']. Multiple fields use OR matching, case-insensitive by default. ['value', 'label'] searches codes and names; fieldNames maps semantic fields to business fields. An empty array matches no items for a nonempty query. Values are compared as strings; object traversal, object values and pinyin matching require a custom callback. A custom callback takes precedence and decides case handling itself. Remote results use the existing protocol for disabling local filtering. Cascader retains path semantics and checks the configured fields on each path node.

Loading options through a function prop

Pass options(query, { signal }) directly; useAsyncData is unnecessary. options still accepts arrays, and an explicit array, including [], takes precedence. The component manages loading, stale-result isolation and cancellation. load-error reports failures, and the instance refresh() method retries. A business loader may accept only query and ignore the second argument.

filterable enables entering a search query. filterOption controls only local matching and never sends requests. With an options loader, remote results are not filtered again by default; with only an array, local matching is enabled by default. Most callers do not need filter-option.

<c-select v-model="value" :options="loadOptions" filterable />

empty-value accepts explicit null (or () => null). Clearing publishes null unchanged; omitted values preserve the existing default. Editors render null as blank without converting ordinary empty-string input to null. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

Cancellable hooks use (payload, done, context): closure payloads contain { action }, change/commit payloads contain { value, previousValue }, and Popup uses { reason }. Context provides signal and an optional original event. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise<void> allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.