15 KiB
title | lang |
---|---|
Select | en-US |
Select
When there are plenty of options, use a drop-down menu to display and select desired ones.
Basic usage
:::demo v-model
is the value of el-option
that is currently selected.
select/basic-usage
:::
Disabled option
:::demo Set the value of disabled
in el-option
to true
to disable this option.
select/disabled-option
:::
Disabled select
Disable the whole component.
:::demo Set disabled
of el-select
to make it disabled.
select/disabled
:::
Clearable single select
You can clear Select using a clear icon.
:::demo Set clearable
attribute for el-select
and a clear icon will appear. Note that clearable
is only for single select.
select/clearable
:::
Basic multiple select
Multiple select uses tags to display selected options.
:::demo Set multiple
attribute for el-select
to enable multiple mode. In this case, the value of v-model
will be an array of selected options. By default the selected options will be displayed as Tags. You can collapse them to a text by using collapse-tags
attribute. You can check them when mouse hover collapse text by using collapse-tags-tooltip
attribute.
select/multiple
:::
Custom template
You can customize HTML templates for options.
:::demo Insert customized HTML templates into the slot of el-option
.
select/custom-template
:::
Grouping
Display options in groups.
:::demo Use el-option-group
to group the options, and its label
attribute stands for the name of the group.
select/grouping
:::
Option filtering
You can filter options for your desired ones.
:::demo Adding filterable
to el-select
enables filtering. By default, Select will find all the options whose label
attribute contains the input value. If you prefer other filtering strategies, you can pass the filter-method
. filter-method
is a Function
that gets called when the input value changes, and its parameter is the current input value.
select/filterable
:::
Remote Search
Enter keywords and search data from server.
:::demo Set the value of filterable
and remote
with true
to enable remote search, and you should pass the remote-method
. remote-method
is a Function
that gets called when the input value changes, and its parameter is the current input value. Note that if el-option
is rendered with the v-for
directive, you should add the key
attribute for el-option
. Its value needs to be unique, such as item.value
in the following example.
select/remote-search
:::
Create new items
Create and select new items that are not included in select options
:::demo By using the allow-create
attribute, users can create new items by typing in the input box. Note that for allow-create
to work, filterable
must be true
. This example also demonstrates default-first-option
. When this attribute is set to true
, you can select the first option in the current option list by hitting enter without having to navigate with mouse or arrow keys.
select/allow-create
:::
:::tip
If the binding value of Select is an object, make sure to assign value-key
as its unique identity key name.
:::
Select Attributes
Attribute | Description | Type | Accepted Values | Default |
---|---|---|---|---|
model-value / v-model | binding value | string / number / boolean / object | — | — |
multiple | whether multiple-select is activated | boolean | — | false |
disabled | whether Select is disabled | boolean | — | false |
value-key | unique identity key name for value, required when value is an object | string | — | value |
size | size of Input | string | large/default/small | default |
clearable | whether select can be cleared | boolean | — | false |
collapse-tags | whether to collapse tags to a text when multiple selecting | boolean | — | false |
collapse-tags-tooltip | whether show all selected tags when mouse hover text of collapse-tags. To use this, collapse-tags must be true |
boolean | true / false | false |
multiple-limit | maximum number of options user can select when multiple is true . No limit when set to 0 |
number | — | 0 |
name | the name attribute of select input | string | — | — |
effect | Tooltip theme, built-in theme: dark / light |
string | string | light |
autocomplete | the autocomplete attribute of select input | string | — | off |
placeholder | placeholder | string | — | Select |
filterable | whether Select is filterable | boolean | — | false |
allow-create | whether creating new items is allowed. To use this, filterable must be true |
boolean | — | false |
filter-method | custom filter method | function | — | — |
remote | whether options are loaded from server | boolean | — | false |
remote-method | custom remote search method | function | — | — |
loading | whether Select is loading data from server | boolean | — | false |
loading-text | displayed text while loading data from server | string | — | Loading |
no-match-text | displayed text when no data matches the filtering query, you can also use slot empty |
string | — | No matching data |
no-data-text | displayed text when there is no options, you can also use slot empty |
string | — | No data |
popper-class | custom class name for Select's dropdown | string | — | — |
reserve-keyword | when multiple and filter is true, whether to reserve current keyword after selecting an option |
boolean | — | true |
default-first-option | select first matching option on enter key. Use with filterable or remote |
boolean | - | false |
popper-append-to-body(deprecated) | whether to append the popper menu to body. If the positioning of the popper is wrong, you can try to set this prop to false | boolean | - | true |
teleported | whether select dropdown is teleported to the body | boolean | true / false | true |
persistent | when select dropdown is inactive and persistent is false , select dropdown will be destroyed |
boolean | true / false | true |
automatic-dropdown | for non-filterable Select, this prop decides if the option menu pops up when the input is focused | boolean | - | false |
clear-icon | Custom clear icon component | string | Component |
— | CircleClose |
fit-input-width | whether the width of the dropdown is the same as the input | boolean | — | false |
suffix-icon | Custom suffix icon component | string | Component |
— | ArrowUp |
tag-type | tag type | string | success/info/warning/danger | info |
validate-event | whether to trigger form validation | boolean | - | true |
Select Events
Event Name | Description | Parameters |
---|---|---|
change | triggers when the selected value changes | current selected value |
visible-change | triggers when the dropdown appears/disappears | true when it appears, and false otherwise |
remove-tag | triggers when a tag is removed in multiple mode | removed tag value |
clear | triggers when the clear icon is clicked in a clearable Select | — |
blur | triggers when Input blurs | (event: Event) |
focus | triggers when Input focuses | (event: Event) |
Select Slots
Name | Description | Subtags |
---|---|---|
— | Option component list | Option Group / Option |
prefix | content as Select prefix | — |
empty | content when there is no options | — |
Option Group Attributes
Attribute | Description | Type | Accepted Values | Default |
---|---|---|---|---|
label | name of the group | string | — | — |
disabled | whether to disable all options in this group | boolean | — | false |
Option Group Slots
Name | Description | Subtags |
---|---|---|
- | customize default content | Option |
Option Attributes
Attribute | Description | Type | Accepted Values | Default |
---|---|---|---|---|
value | value of option | string / number / boolean / object | — | — |
label | label of option, same as value if omitted |
string/number | — | — |
disabled | whether option is disabled | boolean | — | false |
Option Slots
Name | Description |
---|---|
— | customize default content |
Methods
Method | Description | Parameters |
---|---|---|
focus | focus the Input component | - |
blur | blur the Input component, and hide the dropdown | - |