element-plus/docs/en-US/component/select.md

# Select

When there are plenty of options, use a drop-down menu to display and select desired ones.

<style lang="scss">
.example-showcase .el-select {
  width: 240px;
}
</style>

## 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.

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/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 |

## 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                      |
| ------ | -------------------------------- |
| —      | Option component list            |
| 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 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   |

## Methods

| Method | Description                                     | Parameters |
| ------ | ----------------------------------------------- | ---------- |
| focus  | focus the Input component                       | -          |
| blur   | blur the Input component, and hide the dropdown | -          |