2020-08-13 15:18:26 +08:00
## 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.
```html
< template >
< el-select v-model = "value" placeholder = "Select" >
< el-option
v-for="item in options"
:key="item.value"
:label="item.label"
2021-09-04 19:29:28 +08:00
:value="item.value"
>
2020-08-13 15:18:26 +08:00
< / el-option >
< / el-select >
< / template >
< script >
export default {
data() {
return {
2021-09-04 19:29:28 +08:00
options: [
{
value: 'Option1',
label: 'Option1',
},
{
value: 'Option2',
label: 'Option2',
},
{
value: 'Option3',
label: 'Option3',
},
{
value: 'Option4',
label: 'Option4',
},
{
value: 'Option5',
label: 'Option5',
},
],
value: '',
2020-08-13 15:18:26 +08:00
}
2021-09-04 19:29:28 +08:00
},
2020-08-13 15:18:26 +08:00
}
< / script >
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### Disabled option
:::demo Set the value of `disabled` in `el-option` to `true` to disable this option.
```html
< template >
< el-select v-model = "value" placeholder = "Select" >
< el-option
v-for="item in options"
:key="item.value"
:label="item.label"
:value="item.value"
2021-09-04 19:29:28 +08:00
:disabled="item.disabled"
>
2020-08-13 15:18:26 +08:00
< / el-option >
< / el-select >
< / template >
< script >
export default {
data() {
return {
2021-09-04 19:29:28 +08:00
options: [
{
value: 'Option1',
label: 'Option1',
},
{
value: 'Option2',
label: 'Option2',
disabled: true,
},
{
value: 'Option3',
label: 'Option3',
},
{
value: 'Option4',
label: 'Option4',
},
{
value: 'Option5',
label: 'Option5',
},
],
value: '',
2020-08-13 15:18:26 +08:00
}
2021-09-04 19:29:28 +08:00
},
2020-08-13 15:18:26 +08:00
}
< / script >
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### Disabled select
Disable the whole component.
:::demo Set `disabled` of `el-select` to make it disabled.
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
```html
< template >
< el-select v-model = "value" disabled placeholder = "Select" >
< el-option
v-for="item in options"
:key="item.value"
:label="item.label"
2021-09-04 19:29:28 +08:00
:value="item.value"
>
2020-08-13 15:18:26 +08:00
< / el-option >
< / el-select >
< / template >
< script >
export default {
data() {
return {
2021-09-04 19:29:28 +08:00
options: [
{
value: 'Option1',
label: 'Option1',
},
{
value: 'Option2',
label: 'Option2',
},
{
value: 'Option3',
label: 'Option3',
},
{
value: 'Option4',
label: 'Option4',
},
{
value: 'Option5',
label: 'Option5',
},
],
value: '',
2020-08-13 15:18:26 +08:00
}
2021-09-04 19:29:28 +08:00
},
2020-08-13 15:18:26 +08:00
}
< / script >
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### 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.
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
```html
< template >
< el-select v-model = "value" clearable placeholder = "Select" >
< el-option
v-for="item in options"
:key="item.value"
:label="item.label"
2021-09-04 19:29:28 +08:00
:value="item.value"
>
2020-08-13 15:18:26 +08:00
< / el-option >
< / el-select >
< / template >
< script >
export default {
data() {
return {
2021-09-04 19:29:28 +08:00
options: [
{
value: 'Option1',
label: 'Option1',
},
{
value: 'Option2',
label: 'Option2',
},
{
value: 'Option3',
label: 'Option3',
},
{
value: 'Option4',
label: 'Option4',
},
{
value: 'Option5',
label: 'Option5',
},
],
value: '',
2020-08-13 15:18:26 +08:00
}
2021-09-04 19:29:28 +08:00
},
2020-08-13 15:18:26 +08:00
}
< / script >
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### 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.
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
```html
< template >
< el-select v-model = "value1" multiple placeholder = "Select" >
< el-option
v-for="item in options"
:key="item.value"
:label="item.label"
2021-09-04 19:29:28 +08:00
:value="item.value"
>
2020-08-13 15:18:26 +08:00
< / el-option >
< / el-select >
2021-02-07 19:12:59 +08:00
2020-08-13 15:18:26 +08:00
< el-select
v-model="value2"
multiple
collapse-tags
style="margin-left: 20px;"
2021-09-04 19:29:28 +08:00
placeholder="Select"
>
2020-08-13 15:18:26 +08:00
< el-option
v-for="item in options"
:key="item.value"
:label="item.label"
2021-09-04 19:29:28 +08:00
:value="item.value"
>
2020-08-13 15:18:26 +08:00
< / el-option >
< / el-select >
< / template >
< script >
export default {
data() {
return {
2021-09-04 19:29:28 +08:00
options: [
{
value: 'Option1',
label: 'Option1',
},
{
value: 'Option2',
label: 'Option2',
},
{
value: 'Option3',
label: 'Option3',
},
{
value: 'Option4',
label: 'Option4',
},
{
value: 'Option5',
label: 'Option5',
},
],
2020-08-13 15:18:26 +08:00
value1: [],
2021-09-04 19:29:28 +08:00
value2: [],
2020-08-13 15:18:26 +08:00
}
2021-09-04 19:29:28 +08:00
},
2020-08-13 15:18:26 +08:00
}
< / script >
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### Custom template
You can customize HTML templates for options.
:::demo Insert customized HTML templates into the slot of `el-option` .
```html
< template >
< el-select v-model = "value" placeholder = "Select" >
< el-option
v-for="item in cities"
:key="item.value"
:label="item.label"
2021-09-04 19:29:28 +08:00
:value="item.value"
>
2020-08-13 15:18:26 +08:00
< span style = "float: left" > {{ item.label }}< / span >
2021-09-04 19:29:28 +08:00
< span
style="float: right; color: var(--el-text-color-secondary); font-size: 13px"
>{{ item.value }}< /span
>
2020-08-13 15:18:26 +08:00
< / el-option >
< / el-select >
< / template >
< script >
export default {
data() {
return {
2021-09-04 19:29:28 +08:00
cities: [
{
value: 'Beijing',
label: 'Beijing',
},
{
value: 'Shanghai',
label: 'Shanghai',
},
{
value: 'Nanjing',
label: 'Nanjing',
},
{
value: 'Chengdu',
label: 'Chengdu',
},
{
value: 'Shenzhen',
label: 'Shenzhen',
},
{
value: 'Guangzhou',
label: 'Guangzhou',
},
],
value: '',
2020-08-13 15:18:26 +08:00
}
2021-09-04 19:29:28 +08:00
},
2020-08-13 15:18:26 +08:00
}
< / script >
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### 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.
```html
< template >
< el-select v-model = "value" placeholder = "Select" >
< el-option-group
v-for="group in options"
:key="group.label"
2021-09-04 19:29:28 +08:00
:label="group.label"
>
2020-08-13 15:18:26 +08:00
< el-option
v-for="item in group.options"
:key="item.value"
:label="item.label"
2021-09-04 19:29:28 +08:00
:value="item.value"
>
2020-08-13 15:18:26 +08:00
< / el-option >
< / el-option-group >
< / el-select >
< / template >
< script >
export default {
data() {
return {
2021-09-04 19:29:28 +08:00
options: [
{
label: 'Popular cities',
options: [
{
value: 'Shanghai',
label: 'Shanghai',
},
{
value: 'Beijing',
label: 'Beijing',
},
],
},
{
label: 'City name',
options: [
{
value: 'Chengdu',
label: 'Chengdu',
},
{
value: 'Shenzhen',
label: 'Shenzhen',
},
{
value: 'Guangzhou',
label: 'Guangzhou',
},
{
value: 'Dalian',
label: 'Dalian',
},
],
},
],
value: '',
2020-08-13 15:18:26 +08:00
}
2021-09-04 19:29:28 +08:00
},
2020-08-13 15:18:26 +08:00
}
< / script >
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### 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.
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
```html
< template >
< el-select v-model = "value" filterable placeholder = "Select" >
< el-option
v-for="item in options"
:key="item.value"
:label="item.label"
2021-09-04 19:29:28 +08:00
:value="item.value"
>
2020-08-13 15:18:26 +08:00
< / el-option >
< / el-select >
< / template >
< script >
export default {
data() {
return {
2021-09-04 19:29:28 +08:00
options: [
{
value: 'Option1',
label: 'Option1',
},
{
value: 'Option2',
label: 'Option2',
},
{
value: 'Option3',
label: 'Option3',
},
{
value: 'Option4',
label: 'Option4',
},
{
value: 'Option5',
label: 'Option5',
},
],
value: '',
2020-08-13 15:18:26 +08:00
}
2021-09-04 19:29:28 +08:00
},
2020-08-13 15:18:26 +08:00
}
< / script >
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### 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.
```html
< template >
< el-select
v-model="value"
multiple
filterable
remote
reserve-keyword
placeholder="Please enter a keyword"
:remote-method="remoteMethod"
2021-09-04 19:29:28 +08:00
:loading="loading"
>
2020-08-13 15:18:26 +08:00
< el-option
v-for="item in options"
:key="item.value"
:label="item.label"
2021-09-04 19:29:28 +08:00
:value="item.value"
>
2020-08-13 15:18:26 +08:00
< / el-option >
< / el-select >
< / template >
< script >
export default {
data() {
return {
options: [],
value: [],
list: [],
loading: false,
2021-09-04 19:29:28 +08:00
states: [
'Alabama',
'Alaska',
'Arizona',
'Arkansas',
'California',
'Colorado',
'Connecticut',
'Delaware',
'Florida',
'Georgia',
'Hawaii',
'Idaho',
'Illinois',
'Indiana',
'Iowa',
'Kansas',
'Kentucky',
'Louisiana',
'Maine',
'Maryland',
'Massachusetts',
'Michigan',
'Minnesota',
'Mississippi',
'Missouri',
'Montana',
'Nebraska',
'Nevada',
'New Hampshire',
'New Jersey',
'New Mexico',
'New York',
'North Carolina',
'North Dakota',
'Ohio',
'Oklahoma',
'Oregon',
'Pennsylvania',
'Rhode Island',
'South Carolina',
'South Dakota',
'Tennessee',
'Texas',
'Utah',
'Vermont',
'Virginia',
'Washington',
'West Virginia',
'Wisconsin',
'Wyoming',
],
2020-08-13 15:18:26 +08:00
}
},
mounted() {
2021-09-04 19:29:28 +08:00
this.list = this.states.map((item) => {
return { value: `value:${item}` , label: `label:${item}` }
})
2020-08-13 15:18:26 +08:00
},
methods: {
remoteMethod(query) {
if (query !== '') {
2021-09-04 19:29:28 +08:00
this.loading = true
2020-08-13 15:18:26 +08:00
setTimeout(() => {
2021-09-04 19:29:28 +08:00
this.loading = false
this.options = this.list.filter((item) => {
return item.label.toLowerCase().indexOf(query.toLowerCase()) > -1
})
}, 200)
2020-08-13 15:18:26 +08:00
} else {
2021-09-04 19:29:28 +08:00
this.options = []
2020-08-13 15:18:26 +08:00
}
2021-09-04 19:29:28 +08:00
},
},
2020-08-13 15:18:26 +08:00
}
< / script >
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
### Create new items
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
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.
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
```html
< template >
< el-select
v-model="value"
multiple
filterable
allow-create
default-first-option
2021-09-04 19:29:28 +08:00
placeholder="Choose tags for your article"
>
2020-08-13 15:18:26 +08:00
< el-option
v-for="item in options"
:key="item.value"
:label="item.label"
2021-09-04 19:29:28 +08:00
:value="item.value"
>
2020-08-13 15:18:26 +08:00
< / el-option >
< / el-select >
< / template >
< script >
export default {
data() {
return {
2021-09-04 19:29:28 +08:00
options: [
{
value: 'HTML',
label: 'HTML',
},
{
value: 'CSS',
label: 'CSS',
},
{
value: 'JavaScript',
label: 'JavaScript',
},
],
value: [],
2020-08-13 15:18:26 +08:00
}
2021-09-04 19:29:28 +08:00
},
2020-08-13 15:18:26 +08:00
}
< / script >
```
2021-09-04 19:29:28 +08:00
2020-08-13 15:18:26 +08:00
:::
:::tip
If the binding value of Select is an object, make sure to assign `value-key` as its unique identity key name.
:::
### Select Attributes
2021-09-04 19:29:28 +08:00
| 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/medium/small/mini | large |
| clearable | whether select can be cleared | boolean | — | false |
| collapse-tags | whether to collapse tags to a text when multiple selecting | boolean | — | 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 | — | — |
| 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 | — | false |
| default-first-option | select first matching option on enter key. Use with `filterable` or `remote` | boolean | - | false |
| popper-append-to-body | 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 |
| 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 class | string | — | el-icon-circle-close |
2020-08-13 15:18:26 +08:00
### Select Events
2021-09-04 19:29:28 +08:00
| 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) |
2020-08-13 15:18:26 +08:00
### Select Slots
2021-09-04 19:29:28 +08:00
| Name | Description |
| ------ | -------------------------------- |
| — | Option component list |
| prefix | content as Select prefix |
2020-08-13 15:18:26 +08:00
| empty | content when there is no options |
### Option Group Attributes
2021-09-04 19:29:28 +08:00
| Attribute | Description | Type | Accepted Values | Default |
| --------- | -------------------------------------------- | ------- | --------------- | ------- |
| label | name of the group | string | — | — |
| disabled | whether to disable all options in this group | boolean | — | false |
2020-08-13 15:18:26 +08:00
### Option Attributes
2021-09-04 19:29:28 +08:00
| 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 |
2020-08-13 15:18:26 +08:00
### Methods
2021-09-04 19:29:28 +08:00
| Method | Description | Parameters |
| ------ | ----------------------------------------------- | ---------- |
| focus | focus the Input component | - |
| blur | blur the Input component, and hide the dropdown | - |
