element-plus/docs/en-US/component/select-v2.md
Calum Knott 4f58afb7dd
docs: [select-v2] simplify description (#5893)
Co-authored-by: Kevin <sxzz@sxzz.moe>
2022-02-11 00:42:45 +08:00

182 lines
11 KiB
Markdown

---
title: Virtualized Select
lang: en-US
---
# <ElBadge value="beta">Select V2 virtualized selector</ElBadge>
:::tip
This component is still under testing, if you found any bug or issue please report it at [Github](https://github.com/element-plus/element-plus/issues) for us to fix.
:::
## Background
In some use-cases, a single selector may end up loading tens of thousands of rows of data.
Rendering that much data into the DOM could be a burden to the browser, which can result in performance issues.
For a better user and developer experience, we decided to add this component.
## Basic usage
The simplest selector
:::demo
select-v2/basic-usage
:::
## Multi select
The basic multi-select selector with tags
:::demo
select-v2/multiple
:::
## Hide extra tags when the selected items are too many.
:::demo
select-v2/hide-extra-tags
:::
## Filterable multi-select
When the options are overwhelmingly too many, you can use `filterable` option to enable filter feature for finding out the desired option
:::demo
select-v2/filterable
:::
## Disabled selector and select options
You can choose to disable selector itself or the option.
:::demo
select-v2/disabled
:::
## Option Grouping
We can group option as we wanted, as long as the data satisfies the pattern.
:::demo
select-v2/grouping
:::
## Customized option renderer
We can define our own template for rendering the option in the popup.
:::demo
select-v2/customized-option
:::
## Clearable selector
We can clear all the selected options at once, also applicable for single select.
:::demo
select-v2/clearable
:::
## Create Option
Create and select new items that are not included in select options
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`.
:::tip
It will be better to set `:reserve-keyword="false"` when use `allow-create`
:::
:::demo
select-v2/allow-create
:::
## 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.
select-v2/remote-search
:::
## SelectV2 Attributes
| Param | Description | Type | Accepted Values | Default |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------- | ------------- |
| model-value / v-model | biding value | string / number / boolean / object | — | — |
| multiple | is multiple | boolean | — | false |
| disabled | is disabled | boolean | — | false |
| value-key | unique identity key name for value, required when value is an object | string | — | value |
| size | input box size | string | large/default/small | default |
| clearable | whether select can be cleared | boolean | — | false |
| clear-icon | custom clear icon | string / component | — | CircleClose |
| 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 | autocomplete of select input | string | — | off |
| placeholder | the autocomplete attribute of select input | string | — | Please select |
| filterable | is filterable | boolean | — | false |
| allow-create | whether creating new items is allowed. To use this, `filterable` must be true | boolean | — | false |
| reserve-keyword | whether reserve the keyword after select filtered option. | boolean | — | true |
| 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 | — | — |
| 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 | - | false |
| teleported | whether select dropdown is teleported to the body | boolean | true / false | true |
| popper-options | Customized popper option see more at [popper.js](https://popper.js.org/documentation.html) | object | - | - |
| automatic-dropdown | for non-filterable Select, this prop decides if the option menu pops up when the input is focused | boolean | - | false |
| clear-icon | Customized clear icon component | string / Component | — | CircleClose |
| height | The height of the dropdown panel, 34px for each item | number | - | 170 |
| scrollbar-always-on | Controls whether the scrollbar is always displayed | boolean | - | false |
| remote | whether search data from server | boolean | — | false |
| remote-method | function that gets called when the input value changes. Its parameter is the current input value. To use this, `filterable` must be true | function(keyword: string) | — | — |
<span style="display: none;">
<!-- | default-first-option | 在输入框按下回车,选择第一个匹配项。需配合 `filterable``remote` 使用 | boolean | - | false |
| filter-method | 自定义搜索方法 | function | — | — |
| loading | 是否正在从远程获取数据 | boolean | — | false |
| loading-text | 远程加载时显示的文字 | string | — | 加载中 | -->
</span>
## SelectV2 Events
| Event Name | Description | Params |
| -------------- | ------------------------------------------------------------- | ----------------------------------------- |
| 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) |
## SelectV2 Slots
| name | Description |
| ------- | ----------------------------- |
| default | Option renderer |
| empty | content when options is empty |
| prefix | prefix content of input |