element-plus/docs/en-US/component/select.md
jeremywu 8fdf558b04
fix(docs): adding title for components (#4025)
- Remove `type` field.
- Add `title` field
2021-10-25 15:21:08 +08:00

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

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

:::

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