Select

A custom wrapper for theelement-plus selectcomponent, simplifying traversal operations.

Basic Usage

Option Groups

Disabled State

Object Value

Properties

Property	Description	Type	Extensible	Default Value
v-model	Bound value of the selected item	enum stringnumberbooleanobjectarray	No	-
options	List of options	SelectOption[]	Yes	[]
clearable	Whether the option can be cleared	boolean	No	false
multiple	Whether multiple selection is allowed	boolean	No	false
disabled	Whether the select is disabled	boolean	No	false
value-key	Key name used as the unique identifier for the value. Required when the bound value is an object	string	No	value
size	Size of the input box	enum ''largedefaultsmall	No	—
collapse-tags	Whether to display selected values as text in multiple selection mode	boolean	No	false
collapse-tags-tooltip	Whether to show all selected tags when hovering over the collapsed tag. Requires collapse-tags to be true	boolean	No	false
multiple-limit	In multiple selection mode, the maximum number of items that can be selected. 0 means unlimited	number	No	0
name	Native name attribute	string	No	—
effect	Tooltip theme	enum darklight	No	light
autocomplete	Native autocomplete attribute	string	No	off
placeholder	Placeholder text	string	No	—
filterable	Whether the options can be filtered	boolean	No	false
allow-create	Whether to allow users to create new items. Only effective when filterable is true.	boolean	No	false
filter-method	Custom filtering method	Function	No	—
remote	Whether the options are loaded from a remote server	boolean	No	false
remote-method	Custom remote search method	Function	No	—
remote-show-suffix	Display suffix icon for remote search method	boolean	No	false
loading	Whether data is being fetched from a remote source	boolean	No	false
loading-text	Text to display when loading data from the server	string	No	-
no-match-text	Text to display when no matches are found	string	No	-
no-data-text	Text to display when no options are available	string	No	-
popper-class	Custom class name for the dropdown menu	string	No	''
reserve-keyword	Whether to retain the current search keyword after selecting an option when multiple and filterable are true	boolean	No	true
default-first-option	Whether to select the first matching item when pressing Enter in the input box. Requires filterable or remote	boolean	No	false
teleported	Whether to append the dropdown list to the body element	boolean	No	true
persistent	Whether the dropdown selector will be removed when it is not activated and persistent is false	boolean	No	true
automatic-dropdown	Whether to automatically open the options menu when the input box gains focus for non-searchable Select	boolean	No	false
clear-icon	Custom clear icon	enum stringobject	No	CircleClose
fit-input-width	Whether the width of the dropdown matches the input box width	boolean	No	false
suffix-icon	Custom suffix icon component	enum stringobject	No	ArrowDown
suffix-transition deprecated	Animation for suffix icon when the dropdown menu shows or hides	boolean	No	true
tag-type	Tag type	enum ''successinfowarningdanger	No	info
tag-effect el^2.7.7	Tag effect	enum ''lightdarkplain	No	light
validate-event	Whether to trigger form validation	boolean	No	true
placement	Position of the dropdown menu	enum toptop-starttop-endbottombottom-startbottom-endleftleft-startleft-endrightright-startright-end	No	bottom-start
max-collapse-tags	Maximum number of tags to display when collapse-tags is true	number	No	1
popper-options	popper.js options	object	No	-
aria-label	Equivalent to the native input aria-label attribute	string	No	-
empty-values el^2.7.0	Configuration for empty values in the component. See config-provider	array	No	-
value-on-clear el^2.7.0	Value for clearing options. See config-provider	enum stringnumberbooleanFunction	No	-

SelectOption

Property	Description	Type	Required	Default Value
label	Option name	string	Yes	-
value	Option value	enum stringnumberbooleanobject	Yes	-
disabled	Whether disabled	boolean	No	false
options	Option group list	BaseOption[]	No	-

Events

This component supports all native events of Element Plus Select. All events are automatically forwarded to the underlying el-select component.

Common Event Examples:

Event	Description	Type
change	Triggered when the selected value changes	Function (value) => void
visible-change	Triggered when the dropdown appears/hides	Function (visible) => void
remove-tag	Triggered when removing a tag in multiple selection mode	Function (value) => void
clear	Triggered when the clear button is clicked in single-select mode	Function () => void
blur	Triggered when the input loses focus	Function (event) => void
focus	Triggered when the input gains focus	Function (event) => void

💡 Multi-version Compatibility: Supports all Element Plus 2.x versions, including future events that will be automatically available.

💡 Wrapper Default: EzSelect keeps its default behavior aligned with the underlying el-select and does not force clearable. Pass clearable explicitly when you need clear support.

💡 Object Value Tip: When v-model binds to object values, always provide value-key (for example id). This avoids unstable selection echo and follows Element Plus object comparison behavior.