Searchable Select
Searchable Select allows users to select one or multiple items from a list of options. It provides a search input field to filter the options.
<script setup lang="ts">import { VSearchableSelect, VOption } from '@vonage/vivid-api-vue';</script>
<template> <VSearchableSelect label="Country"> <VOption value="AF" text="Afghanistan" /> <VOption value="AL" text="Albania" /> <VOption value="DZ" text="Algeria" /> </VSearchableSelect></template>import { registerSearchableSelect } from '@vonage/vivid-api';
registerSearchableSelect('your-prefix');<script type="module"> import { registerSearchableSelect, registerOption } from '@vonage/vivid-api'; registerSearchableSelect('your-prefix'); registerOption('your-prefix');</script>
<your-prefix-searchable-select label="Country"> <your-prefix-option value="AF" text="Afghanistan"></your-prefix-option> <your-prefix-option value="AL" text="Albania"></your-prefix-option> <your-prefix-option value="DZ" text="Algeria"></your-prefix-option></your-prefix-searchable-select>For a single select, you can control the selected value by setting the value attribute.
<script setup lang="ts">import { VSearchableSelect, VOption } from '@vonage/vivid-api-vue';</script>
<template> <VSearchableSelect label="Country" value="AL"> <VOption value="AF" text="Afghanistan" /> <VOption value="AL" text="Albania" /> <VOption value="DZ" text="Algeria" /> </VSearchableSelect></template><vwc-searchable-select label="Country" value="AL"> <vwc-option value="AF" text="Afghanistan"></vwc-option> <vwc-option value="AL" text="Albania"></vwc-option> <vwc-option value="DZ" text="Algeria"></vwc-option></vwc-searchable-select>For multiple select, you can control the selected values by setting the values property.
Web components (as with all HTML elements) can only accept strings as their attributes. values requires an array, so it has to be set programmatically.
<script setup lang="ts">import { ref } from 'vue';import { VSearchableSelect, VOption, VFlag } from '@vonage/vivid-api-vue';
const values = ref(['AF', 'DZ']);
</script>
<template> <VSearchableSelect v-model:values="values" multiple label="Countries"> <VOption value="AF" text="Afghanistan"> <template #icon> <VFlag code="AF" /> </template> </VOption> <VOption value="AL" text="Albania"> <template #icon> <VFlag code="AL" /> </template> </VOption> <VOption value="DZ" text="Algeria"> <template #icon> <VFlag code="DZ" /> </template> </VOption> </VSearchableSelect></template><vwc-searchable-select multiple label="Countries"> <vwc-option value="AF" text="Afghanistan"> <vwc-flag slot="icon" code="AF"></vwc-flag> </vwc-option> <vwc-option value="AL" text="Albania"> <vwc-flag slot="icon" code="AL"></vwc-flag> </vwc-option> <vwc-option value="DZ" text="Algeria"> <vwc-flag slot="icon" code="DZ"></vwc-flag> </vwc-option></vwc-searchable-select><script> customElements.whenDefined('vwc-searchable-select').then(() => { document.querySelector('vwc-searchable-select').values = ['AF', 'DZ']; });</script>Add the fixed-dropdown attribute to change the dropdown to use a fixed position strategy.
This is useful for cases in which the dropdown is obstructed by other elements.
The open attribute allows the Searchable Select to be opened programmatically.
<script setup lang="ts">import { VSearchableSelect, VOption } from '@vonage/vivid-api-vue';</script>
<template> <VSearchableSelect label="Country" open> <VOption value="AF" text="Afghanistan" /> <VOption value="AL" text="Albania" /> <VOption value="DZ" text="Algeria" /> </VSearchableSelect></template><vwc-searchable-select label="Country" open> <vwc-option value="AF" text="Afghanistan"></vwc-option> <vwc-option value="AL" text="Albania"></vwc-option> <vwc-option value="DZ" text="Algeria"></vwc-option></vwc-searchable-select>You can access the current search text through the searchText property and listen for changes through the search-text-change event.
<script setup lang="ts">import { ref } from 'vue';import { VSearchableSelect } from '@vonage/vivid-api-vue';
const searchText = ref('');
function onSearchTextChange(e: Event) {const el = (e?.currentTarget ?? e?.target) as { searchText?: string };console.log('onSearchTextChange', el?.searchText);searchText.value = el?.searchText ?? '';}
</script>
<template> <div>Current search text: "<span v-text="searchText"></span>"</div> <VSearchableSelect @search-text-change="onSearchTextChange" /></template><div>Current search text: "<span id="search-text"></span>"</div><vwc-searchable-select></vwc-searchable-select>
<script> customElements.whenDefined('vwc-searchable-select').then(() => { document.querySelector('vwc-searchable-select').addEventListener('search-text-change', (e) => { document.querySelector('#search-text').innerText = e.currentTarget.searchText; }); });</script>You can control option filtering by setting optionFilter to a custom function. For example, always returning true will disable filtering by always showing all options.
<script setup lang="ts">import { ref, onMounted } from 'vue';import { VSearchableSelect, VOption, VFlag } from '@vonage/vivid-api-vue';
const selectRef = ref<InstanceType<typeof VSearchableSelect> | null>(null);
onMounted(() => { if (selectRef.value?.element) { selectRef.value.element.optionFilter = () => true; }});</script>
<template> <VSearchableSelect ref="selectRef"> <VOption value="AF" text="Afghanistan"> <template #icon> <VFlag code="AF" /> </template> </VOption> <VOption value="AL" text="Albania"> <template #icon> <VFlag code="AL" /> </template> </VOption> <VOption value="DZ" text="Algeria"> <template #icon> <VFlag code="DZ" /> </template> </VOption> </VSearchableSelect></template><vwc-searchable-select> <vwc-option value="AF" text="Afghanistan"> <vwc-flag slot="icon" code="AF"></vwc-flag> </vwc-option> <vwc-option value="AL" text="Albania"> <vwc-flag slot="icon" code="AL"></vwc-flag> </vwc-option> <vwc-option value="DZ" text="Algeria"> <vwc-flag slot="icon" code="DZ"></vwc-flag> </vwc-option></vwc-searchable-select>
<script> customElements.whenDefined('vwc-searchable-select').then(() => { document.querySelector('vwc-searchable-select').optionFilter = () => true; });</script>Holds the available options as Option elements.
<script setup lang="ts">import { VSearchableSelect, VOption } from '@vonage/vivid-api-vue';</script>
<template> <VSearchableSelect label="Select an option"> <VOption value="1" text="Option 1" /> <VOption value="2" text="Option 2" /> <VOption value="3" text="Option 3" /> </VSearchableSelect></template><vwc-searchable-select label="Select an option"> <vwc-option value="1" text="Option 1"></vwc-option> <vwc-option value="2" text="Option 2"></vwc-option> <vwc-option value="3" text="Option 3"></vwc-option></vwc-searchable-select>You can use the Option’s tag-icon slot to display an icon next to the selected option’s tag.
<script setup lang="ts">import { VSearchableSelect, VOption, VFlag } from '@vonage/vivid-api-vue';</script>
<template> <VSearchableSelect label="Country" clearable multiple> <VOption value="afghanistan" text="Afghanistan" selected> <template #icon> <VFlag code="AF" /> </template> <template #tag-icon> <VFlag code="AF" /> </template> </VOption> <VOption value="albania" text="Albania"> <template #icon> <VFlag code="AL" /> </template> <template #tag-icon> <VFlag code="AL" /> </template> </VOption> <VOption value="algeria" text="Algeria"> <template #icon> <VFlag code="DZ" /> </template> <template #tag-icon> <VFlag code="DZ" /> </template> </VOption> </VSearchableSelect></template><vwc-searchable-select label="Country" clearable multiple> <vwc-option value="afghanistan" text="Afghanistan" selected> <vwc-flag slot="icon" code="AF"></vwc-flag> <vwc-flag slot="tag-icon" code="AF"></vwc-flag> </vwc-option> <vwc-option value="albania" text="Albania"> <vwc-flag slot="icon" code="AL"></vwc-flag> <vwc-flag slot="tag-icon" code="AL"></vwc-flag> </vwc-option> <vwc-option value="algeria" text="Algeria"> <vwc-flag slot="icon" code="DZ"></vwc-flag> <vwc-flag slot="tag-icon" code="DZ"></vwc-flag> </vwc-option></vwc-searchable-select>Hidden Options
Setting hidden on an Option will hide it from the dropdown while still allowing it to be a selected value.
<script setup lang="ts">import { VSearchableSelect, VOption } from '@vonage/vivid-api-vue';</script>
<template> <VSearchableSelect multiple> <VOption value="AF" text="Afghanistan" selected hidden /> <VOption value="AL" text="Albania" /> <VOption value="DZ" text="Algeria" /> </VSearchableSelect></template><vwc-searchable-select multiple> <vwc-option value="AF" text="Afghanistan" selected hidden></vwc-option> <vwc-option value="AL" text="Albania"></vwc-option> <vwc-option value="DZ" text="Algeria"></vwc-option></vwc-searchable-select>Set the icon slot to show an icon at the start of the input.
If set, the icon(deprecated) attribute is ignored.
<script setup lang="ts">import { VSearchableSelect, VOption, VIcon } from '@vonage/vivid-api-vue';</script>
<template> <VSearchableSelect label="Country" multiple> <template #icon> <VIcon name="check-circle-solid" connotation="success" /> </template> <VOption value="AF" text="Afghanistan" selected /> <VOption value="AL" text="Albania" selected /> <VOption value="DZ" text="Algeria" selected /> </VSearchableSelect></template><vwc-searchable-select label="Country" multiple> <vwc-icon slot="icon" name="check-circle-solid" connotation="success"></vwc-icon> <vwc-option value="AF" text="Afghanistan" selected></vwc-option> <vwc-option value="AL" text="Albania" selected></vwc-option> <vwc-option value="DZ" text="Algeria" selected></vwc-option></vwc-searchable-select>Use the meta slot to show meta information at the end of the input field.
<script setup lang="ts">import { VSearchableSelect, VOption, VBadge } from '@vonage/vivid-api-vue';</script>
<template> <VSearchableSelect aria-label="Country" multiple style="width: 250px"> <VOption value="AF" text="Afghanistan" selected /> <VOption value="AL" text="Albania" selected /> <VOption value="DZ" text="Algeria" selected /> <template #meta> <VBadge connotation="success" text="Beta" /> </template> </VSearchableSelect></template><vwc-searchable-select aria-label="Country" multiple> <vwc-option value="AF" text="Afghanistan" selected></vwc-option> <vwc-option value="AL" text="Albania" selected></vwc-option> <vwc-option value="DZ" text="Algeria" selected></vwc-option> <vwc-badge slot="meta" connotation="success" text="Beta"></vwc-badge></vwc-searchable-select>
<style> vwc-searchable-select { width: 250px; }</style>The helper-text slot allows you to use rich content as the helper text.
<script setup lang="ts">import { VSearchableSelect, VOption } from '@vonage/vivid-api-vue';</script>
<template> <VSearchableSelect label="Business Type"> <VOption value="ngo" text="Non-Governmental Organization" /> <VOption value="gov" text="Governmental Organization" /> <VOption value="edu" text="Educational Institution" /> <template #helper-text> <span>Please select the <a href="#">type of your business</a>.</span> </template> </VSearchableSelect></template><vwc-searchable-select label="Business Type"> <vwc-option value="ngo" text="Non-Governmental Organization"></vwc-option> <vwc-option value="gov" text="Governmental Organization"></vwc-option> <vwc-option value="edu" text="Educational Institution"></vwc-option> <span slot="helper-text"> {' '} Please select the <a href="#">type of your business</a>.{' '} </span></vwc-searchable-select>The contextual-help slot allows you to add the Contextual Help component next to the label.
<script setup lang="ts">import { VSearchableSelect, VOption, VContextualHelp } from '@vonage/vivid-api-vue';</script>
<template> <VSearchableSelect label="Business Type"> <VOption value="ngo" text="Non-Governmental Organization" /> <VOption value="gov" text="Governmental Organization" /> <VOption value="edu" text="Educational Institution" /> <template #contextual-help> <VContextualHelp>Please select the type of your business</VContextualHelp> </template> </VSearchableSelect></template><vwc-searchable-select label="Business Type"> <vwc-option value="ngo" text="Non-Governmental Organization"></vwc-option> <vwc-option value="gov" text="Governmental Organization"></vwc-option> <vwc-option value="edu" text="Educational Institution"></vwc-option> <vwc-contextual-help slot="contextual-help">Please select the type of your business</vwc-contextual-help></vwc-searchable-select>You can specify width on the Searchable Select to control the width of the component. The default width is 300px.
The dropdown has min-width of its content.
<script setup lang="ts">import { VSearchableSelect, VOption } from '@vonage/vivid-api-vue';</script>
<template> <VSearchableSelect label="Choose an option" style="width: 140px"> <VOption value="1" text="Option 1: dogs" /> <VOption value="2" text="Option 2: cats" /> <VOption value="3" text="Option 3: dogs and cats" /> </VSearchableSelect></template><style> vwc-searchable-select { width: 140px; }</style><vwc-searchable-select label="Choose an option"> <vwc-option value="1" text="Option 1: dogs"></vwc-option> <vwc-option value="2" text="Option 2: cats"></vwc-option> <vwc-option value="3" text="Option 3: dogs and cats"></vwc-option></vwc-searchable-select>Use --searchable-select-height to set the max-height of the dropdown. The default value is 408px.
<script setup lang="ts">import { VSearchableSelect, VOption } from '@vonage/vivid-api-vue';</script>
<template> <VSearchableSelect class="searchable-select-height-demo" aria-label="Options Selector"> <VOption value="1" text="Option 1" /> <VOption value="2" text="Option 2" /> <VOption value="3" text="Option 3" /> <VOption value="4" text="Option 4" /> <VOption value="5" text="Option 5" /> <VOption value="6" text="Option 6" /> <VOption value="7" text="Option 7" /> </VSearchableSelect></template>
<style scoped>.searchable-select-height-demo { --searchable-select-height: 100px;}</style><style> vwc-searchable-select { --searchable-select-height: 100px; }</style><vwc-searchable-select aria-label="Options Selector"> <vwc-option value="1" text="Option 1"></vwc-option> <vwc-option value="2" text="Option 2"></vwc-option> <vwc-option value="3" text="Option 3"></vwc-option> <vwc-option value="4" text="Option 4"></vwc-option> <vwc-option value="5" text="Option 5"></vwc-option> <vwc-option value="6" text="Option 6"></vwc-option> <vwc-option value="7" text="Option 7"></vwc-option></vwc-searchable-select>| Property | Type | Default | Description |
|---|---|---|---|
| appearance | 'fieldset' | 'ghost' | Sets the appearance of the Searchable Select element. | |
| clearable | boolean | Adds a clear button to the input field that clears the selected values. | |
| deselectAllText | string | Overrides the default "Deselect All" text. | |
| disabled | boolean | Sets the element's disabled state. A disabled element will not be included during form submission. | |
| enableSelectAll | boolean | Adds a "Select All" option at the top of the options list. | |
| errorText | string | Provides a custom error message. Any current error state will be overridden. | |
| externalTags | boolean | ||
| fixedDropdown | boolean | ||
| helperText | string | Provides additional information to help the user enter the correct information. To add HTML to the helper text, use the helper-text slot instead. | |
| iconTrailing | boolean | Indicates the icon affix alignment. | |
| initialValue | string | The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set. | |
| initialValues | string[] | List of initially selected option's values. Used in case of form reset. | |
| label | string | The label for the form element. | |
| loading | boolean | Whether the component is in a loading state. | |
| maxLines | number | ||
| maxSelected | number | ||
| multiple | boolean | ||
| name | string | The name of the element. This element's value will be surfaced during form submission under the provided name. | |
| open | boolean | ||
| optionFilter | ((option: @vonage/vivid-api#VwcOptionElement, searchText: string) => boolean) | Function to filter the options to display. | |
| placeholder | string | ||
| required | boolean | Require the field to be completed prior to form submission. | |
| scale | 'condensed' | 'normal' | Sets the display size of the Searchable Select element. | |
| selectAllText | string | Overrides the default "Select All" text. | |
| selectedIndex | number | ||
| shape | 'rounded' | 'pill' | Sets the shape of the Searchable Select element. | |
| successText | string | Provides a custom success message. Any current error state will be overridden. | |
| value (modelValue) | string | The current value of the element. | |
| values (values) | string[] | List of selected option's values in the order that they have been selected in. |
| Property | Type | Default | Description |
|---|---|---|---|
| appearance | 'fieldset' | 'ghost' | Sets the appearance of the Searchable Select element. | |
| clearable | boolean | Adds a clear button to the input field that clears the selected values. | |
| deselect-all-text | string | Overrides the default "Deselect All" text. | |
| disabled | boolean | Sets the element's disabled state. A disabled element will not be included during form submission. | |
| enable-select-all | boolean | Adds a "Select All" option at the top of the options list. | |
| error-text | string | Provides a custom error message. Any current error state will be overridden. | |
| external-tags | boolean | ||
| fixed-dropdown | boolean | ||
| helper-text | string | Provides additional information to help the user enter the correct information. To add HTML to the helper text, use the helper-text slot instead. | |
| icon-trailing | boolean | Indicates the icon affix alignment. | |
| value | string | The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set. | |
| initialValues (property only) | string[] | List of initially selected option's values. Used in case of form reset. | |
| label | string | The label for the form element. | |
| loading | boolean | Whether the component is in a loading state. | |
| max-lines | number | ||
| max-selected | number | ||
| multiple | boolean | ||
| name | string | The name of the element. This element's value will be surfaced during form submission under the provided name. | |
| open | boolean | ||
| optionFilter (property only) | ((option: @vonage/vivid-api#VwcOptionElement, searchText: string) => boolean) | Function to filter the options to display. | |
| placeholder | string | ||
| required | boolean | Require the field to be completed prior to form submission. | |
| scale | 'condensed' | 'normal' | Sets the display size of the Searchable Select element. | |
| select-all-text | string | Overrides the default "Select All" text. | |
| selectedIndex (property only) | number | ||
| shape | 'rounded' | 'pill' | Sets the shape of the Searchable Select element. | |
| success-text | string | Provides a custom success message. Any current error state will be overridden. | |
| current-value | string | The current value of the element. | |
| values (property only) | string[] | List of selected option's values in the order that they have been selected in. |
| Name | Description |
|---|---|
| contextual-help | Slot for the contextual-help component, displayed next to the label. |
| default | Holds the available options. |
| helper-text | Describes how to use the component. Alternative to the `helper-text` attribute. |
| icon | The preferred way to add an icon to the control. |
| loading-options | Message that appears there are no options to display and the component is in a loading state. |
| meta | Slot to add meta content to the control. |
| no-matches | Message that appears when no options match the search query. |
| no-options | Message that appears when no options are available. |
| Name | Description |
|---|---|
| contextual-help | Slot for the contextual-help component, displayed next to the label. |
| default | Holds the available options. |
| helper-text | Describes how to use the component. Alternative to the `helper-text` attribute. |
| icon | The preferred way to add an icon to the control. |
| loading-options | Message that appears there are no options to display and the component is in a loading state. |
| meta | Slot to add meta content to the control. |
| no-matches | Message that appears when no options match the search query. |
| no-options | Message that appears when no options are available. |
| Name | Type | Description |
|---|---|---|
| change | CustomEvent<undefined> | Fired when the selected options change |
| input | CustomEvent<undefined> | Fired when the selected options change |
| search-text-change | CustomEvent<undefined> | Fired when the search text changes |
| Name | Type | Description |
|---|---|---|
| change | CustomEvent<undefined> | Fired when the selected options change |
| input | CustomEvent<undefined> | Fired when the selected options change |
| search-text-change | CustomEvent<undefined> | Fired when the search text changes |
| Name | Params | Returns | Description |
|---|---|---|---|
| checkValidity | boolean | Return the current validity of the element. | |
| reportValidity | boolean | Return the current validity of the element. If false, fires an invalid event at the element. |
| Property | Type | Default | Description |
|---|---|---|---|
| checked | false | true | The checked state is used when the parent listbox is in multiple selection mode. To avoid accessibility conflicts, the checked state should not be present in single selection mode. | |
| connotation | 'accent' | 'cta' | Sets the connotation that appears when selected | |
| defaultSelected | boolean | Sets the option's initial selected state (mirrors the native `selected` attribute) | |
| disabled | boolean | The disabled state of the option. | |
| iconTrailing | boolean | Indicates the icon affix alignment. | |
| _label | string | ||
| matchedText | string | Text to highlighted as matching a search query | |
| selected | boolean | Indicates whether the option is currently selected | |
| selectedAttribute | boolean | ||
| tagConnotation | 'accent' | 'cta' | When displayed as a tag, the connotation of the tag | |
| _text | string | ||
| textSecondary | string | Secondary text displayed below or next to the primary text | |
| value | string | The value of the option. |
| Property | Type | Default | Description |
|---|---|---|---|
| checked | false | true | The checked state is used when the parent listbox is in multiple selection mode. To avoid accessibility conflicts, the checked state should not be present in single selection mode. | |
| connotation | 'accent' | 'cta' | Sets the connotation that appears when selected | |
| selected | boolean | Sets the option's initial selected state (mirrors the native `selected` attribute) | |
| disabled | boolean | The disabled state of the option. | |
| icon-trailing | boolean | Indicates the icon affix alignment. | |
| label | string | ||
| matched-text | string | Text to highlighted as matching a search query | |
| current-selected | boolean | Indicates whether the option is currently selected | |
| selectedAttribute (property only) | boolean | ||
| tag-connotation | 'accent' | 'cta' | When displayed as a tag, the connotation of the tag | |
| text | string | ||
| text-secondary | string | Secondary text displayed below or next to the primary text | |
| value | string | The value of the option. |
| Name | Description |
|---|---|
| icon | The preferred way to add an icon to the component. |
| tag-icon | Icon to be displayed in the tag when selected inside of Searchable Select. |
| trailing-meta | For additional elements at the end of the Option. |
| Name | Description |
|---|---|
| icon | The preferred way to add an icon to the component. |
| tag-icon | Icon to be displayed in the tag when selected inside of Searchable Select. |
| trailing-meta | For additional elements at the end of the Option. |