Select

Select lets users choose one option from an options menu. Consider using select when you have 4 or more options to choose from.

Usage

import { registerSelect } from '@vonage/vivid-api';

registerSelect('your-prefix');

<script type="module">
  import { registerSelect, registerOption } from '@vonage/vivid-api';
  registerSelect('your-prefix');
  registerOption('your-prefix');
</script>

<your-prefix-select label="Title" placeholder="Select an option">
  <your-prefix-option value="mr" text="Mr"></your-prefix-option>
  <your-prefix-option value="mrs" text="Mrs"></your-prefix-option>
  <your-prefix-option value="miss" text="Miss"></your-prefix-option>
  <your-prefix-option value="ms" text="Ms"></your-prefix-option>
</your-prefix-select>

<script setup lang="ts">
import { VSelect, VOption } from '@vonage/vivid-api-vue';
</script>

<template>
  <VSelect label="Title" placeholder="Select an option">
    <VOption value="mr" text="Mr" />
    <VOption value="mrs" text="Mrs" />
    <VOption value="miss" text="Miss" />
    <VOption value="ms" text="Ms" />
  </VSelect>
</template>

Custom Width

By default, the Select’s width is fit-content and the same goes for the listbox containing the options.

You can specify the width of the Select using CSS.

<script setup lang="ts">
import { VOption, VSelect } from '@vonage/vivid-api-vue';
</script>

<template>
  <VSelect class="select" label="Choose an option">
    <VOption value="1" text="Option 1: dogs" />
    <VOption value="2" text="Option 2: cats" />
    <VOption value="3" text="Option 3: dogs and cats" />
  </VSelect>
</template>

<style scoped>
.select {
  max-width: 320px;
  width: 100%;
}
</style>

<vwc-select class="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-select>

<style>
  .select {
    max-width: 320px;
    width: 100%;
  }
</style>

The fixed-dropdown attribute is useful for cases in which the dropdown is obstructed by other elements.

In the example below, if fixed-dropdown was not set on the Select, the select dropdown would be cut off where the Dialog ends. Also, see the Grid Select example).

<script setup lang="ts">
import { VActionGroup, VButton, VDialog, VDivider, VIcon, VOption, VSelect, VTextField, VFlag } from '@vonage/vivid-api-vue';
import { ref } from 'vue';

const countryCode = ref('1');

</script>

<template>
  <VDialog open headline="Telephone Number" icon-placement="side">
    <template #icon><VIcon name="call-line" label="Call" /></template>
    <template #body>
      <VActionGroup>
        <VSelect fixed-dropdown aria-label="Country code" appearance="ghost" class="country-code" v-model="countryCode">
          <template #icon>
            <VFlag code="US" />
          </template>
          <VOption value="1" text="+1">
            <template #icon>
              <VFlag code="US" />
            </template>
          </VOption>
          <VOption value="44" text="+44">
            <template #icon>
              <VFlag code="UK" />
            </template>
          </VOption>
          <VOption value="49" text="+49">
            <template #icon>
              <VFlag code="DE" />
            </template>
          </VOption>
          <VOption value="355" text="+355">
            <template #icon>
              <VFlag code="AL" />
            </template>
          </VOption>
        </VSelect>
        <VDivider orientation="vertical" />
        <VTextField aria-label="Telephone number" type="tel" inputmode="tel" appearance="ghost" />
      </VActionGroup>
    </template>
    <template #action-items>
      <VButton appearance="filled" label="Submit" />
    </template>
  </VDialog>
</template>

<vwc-dialog open headline="Telephone Number" icon-placement="side">
  <vwc-icon slot="icon" name="call-line" label="Call"></vwc-icon>
  <vwc-action-group slot="body">
    <vwc-select fixed-dropdown aria-label="Country code" appearance="ghost" class="country-code" id="country-code">
      <vwc-flag slot="icon" code="US"></vwc-flag>
      <vwc-option value="1" text="+1">
        <vwc-flag slot="icon" code="US"></vwc-flag>
      </vwc-option>
      <vwc-option value="44" text="+44">
        <vwc-flag slot="icon" code="UK"></vwc-flag>
      </vwc-option>
      <vwc-option value="49" text="+49">
        <vwc-flag slot="icon" code="DE"></vwc-flag>
      </vwc-option>
      <vwc-option value="355" text="+355">
        <vwc-flag slot="icon" code="AL"></vwc-flag>
      </vwc-option>
    </vwc-select>
    <vwc-divider orientation="vertical"></vwc-divider>
    <vwc-text-field aria-label="Telephone number" type="tel" inputmode="tel" appearance="ghost"></vwc-text-field>
  </vwc-action-group>
  <vwc-button slot="action-items" appearance="filled" label="Submit"></vwc-button>
</vwc-dialog>

<script>
  const select = document.getElementById('country-code');
  select?.addEventListener('change', (e) => {
    select.icon = select.selectedOptions[0].icon;
  });
</script>

Open

The open attribute allows the Select to be opened programmatically.

Document elements display precedence is formed by the imaginary z-axis stacking context, commonly by order of which elements are rendered and special properties (e.g. z-index).

Select component is a low level element, unaware of its document context, but is, in most cases, required to overlay on top of all elements. If needed a z-index value can be set on the host.

<script setup lang="ts">
import { VOption, VSelect } from '@vonage/vivid-api-vue';
</script>

<template>
  <VSelect open label="Title" placeholder="Select an option">
    <VOption value="mr" text="Mr" />
    <VOption value="mrs" text="Mrs" />
    <VOption value="miss" text="Miss" />
    <VOption value="ms" text="Ms" />
  </VSelect>
</template>

<vwc-select open label="Title" placeholder="Select an option">
  <vwc-option value="mr" text="Mr"></vwc-option>
  <vwc-option value="mrs" text="Mrs"></vwc-option>
  <vwc-option value="miss" text="Miss"></vwc-option>
  <vwc-option value="ms" text="Ms"></vwc-option>
</vwc-select>

Slots

Default Slot

This is where you place the Option components to provide the option list.

<script setup lang="ts">
import { VOption, VSelect } from '@vonage/vivid-api-vue';
</script>

<template>
  <VSelect label="Title" placeholder="Select an option">
    <VOption value="mr" text="Mr" />
    <VOption value="mrs" text="Mrs" />
    <VOption value="miss" text="Miss" />
    <VOption value="ms" text="Ms" />
  </VSelect>
</template>

<vwc-select label="Title" placeholder="Select an option">
  <vwc-option value="mr" text="Mr"></vwc-option>
  <vwc-option value="mrs" text="Mrs"></vwc-option>
  <vwc-option value="miss" text="Miss"></vwc-option>
  <vwc-option value="ms" text="Ms"></vwc-option>
</vwc-select>

Meta Slot

Set the meta slot to show meta information after the selected option label.

<script setup lang="ts">
import { VBadge, VOption, VSelect } from '@vonage/vivid-api-vue';
</script>

<template>
  <VSelect aria-label="Options Selector" class="select">
    <template #meta>
      <VBadge connotation="success" text="Beta" />
    </template>
    <VOption value="1" text="Option 1" />
    <VOption value="2" text="Option 2" />
    <VOption value="3" text="Option 3" />
  </VSelect>
  <VSelect aria-label="Options Selector" class="select">
    <template #meta>
      <span class="duration">00:00:00</span>
    </template>
    <VOption value="1" text="Option 1" />
    <VOption value="2" text="Option 2" />
    <VOption value="3" text="Option 3" />
  </VSelect>
</template>

<style scoped>
.select {
  width: 250px;
}
.duration {
  color: var(--vvd-color-neutral-600);
  text-align: end;
  flex-grow: 1;
}
</style>

<vwc-select aria-label="Options Selector" class="select">
  <vwc-badge slot="meta" connotation="success" text="Beta"></vwc-badge>
  <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-select>
<vwc-select aria-label="Options Selector" class="select">
  <span slot="meta" class="duration">00:00:00</span>
  <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-select>

<style>
  .select {
    width: 250px;
  }
  .duration {
    color: var(--vvd-color-neutral-600);
    text-align: end;
    flex-grow: 1;
  }
</style>

Icon Slot

Set the icon slot to show an icon before the selected option text. If set, the icon attribute is ignored.

<script setup lang="ts">
import { VIcon, VOption, VSelect } from '@vonage/vivid-api-vue';
</script>

<template>
  <VSelect aria-label="Options Selector" class="select">
    <template #icon>
      <VIcon name="check-circle-solid" connotation="success" />
    </template>
    <VOption value="1" text="Option 1" />
    <VOption value="2" text="Option 2" />
    <VOption value="3" text="Option 3" />
  </VSelect>
</template>

<style scoped>
.select {
  width: 150px;
}
</style>

<vwc-select aria-label="Options Selector" class="select">
  <vwc-icon slot="icon" name="check-circle-solid" connotation="success"></vwc-icon>
  <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-select>

<style>
  .select {
    width: 150px;
  }
</style>

Helper Text Slot

The helper-text slot allows you to use rich content as the select’s helper text.

<script setup lang="ts">
import { VOption, VSelect } from '@vonage/vivid-api-vue';
</script>

<template>
  <VSelect label="Business Type">
    <template #helper-text>
      <span>Please select the <a href="#">type of your business</a>.</span>
    </template>
    <VOption value="ngo" text="Non-Governmental Organization" />
    <VOption value="gov" text="Governmental Organization" />
    <VOption value="edu" text="Educational Institution" />
  </VSelect>
</template>

<vwc-select label="Business Type">
  <span slot="helper-text">
    {' '}
    Please select the <a href="#">type of your business</a>.{' '}
  </span>
  <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-select>

Contextual Help Slot

The contextual-help slot allows you to add the Contextual Help component next to the label.

<script setup lang="ts">
import { VContextualHelp, VOption, VSelect } from '@vonage/vivid-api-vue';
</script>

<template>
  <VSelect label="Business Type">
    <template #contextual-help>
      <VContextualHelp>Please select the type of your business</VContextualHelp>
    </template>
    <VOption value="ngo" text="Non-Governmental Organization" />
    <VOption value="gov" text="Governmental Organization" />
    <VOption value="edu" text="Educational Institution" />
  </VSelect>
</template>

<vwc-select label="Business Type">
  <vwc-contextual-help slot="contextual-help">Please select the type of your business</vwc-contextual-help>
  <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-select>

CSS Variables

Use --select-height to customize the max-height of the dropdown.

<script setup lang="ts">
import { VOption, VSelect } from '@vonage/vivid-api-vue';
</script>

<template>
  <VSelect aria-label="Options Selector" class="select">
    <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" />
  </VSelect>
</template>

<style scoped>
.select {
  --select-height: 150px;
}
</style>

<vwc-select aria-label="Options Selector" class="select">
  <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-select>

<style>
  .select {
    --select-height: 150px;
  }
</style>

API Reference

select

Properties

Property	Type	Description
appearance	`'fieldset' \| 'ghost'`	Sets the element's appearance
clearable	`boolean`	Adds a clear button to the select that clears the selected value(s).
disabled	`boolean`	Sets the element's disabled state. A disabled element will not be included during form submission.
errorText	`string`	Provides a custom error message. Any current error state will be overridden.
fixedDropdown	`boolean`	Sets the position strategy of the dropdown to fixed
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.
label	`string`	The label for the form element.
multiple	`boolean`	Indicates if the listbox is in multi-selection mode.
name	`string`	The name of the element. This element's value will be surfaced during form submission under the provided name.
open	`boolean`	Sets the element's menu to be open
options	`@vonage/vivid-api#VwcOptionElement[]`	The list of options.
placeholder	`string`	Sets the text to be displayed when no option is selected
required	`boolean`	Require the field to be completed prior to form submission.
scale	`'condensed' \| 'normal'`	Sets the display size of the input element
selectedIndex	`number`	The index of the selected option.
selectedOptions	`@vonage/vivid-api#VwcOptionElement[]`	A collection of the selected options.
shape	`'rounded' \| 'pill'`	Sets the shape of the 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.

Property	Type	Description
appearance	`'fieldset' \| 'ghost'`	Sets the element's appearance
clearable	`boolean`	Adds a clear button to the select that clears the selected value(s).
disabled	`boolean`	Sets the element's disabled state. A disabled element will not be included during form submission.
error-text	`string`	Provides a custom error message. Any current error state will be overridden.
fixed-dropdown	`boolean`	Sets the position strategy of the dropdown to fixed
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.
label	`string`	The label for the form element.
multiple	`boolean`	Indicates if the listbox is in multi-selection mode.
name	`string`	The name of the element. This element's value will be surfaced during form submission under the provided name.
open	`boolean`	Sets the element's menu to be open
options (property only)	`@vonage/vivid-api#VwcOptionElement[]`	The list of options.
placeholder	`string`	Sets the text to be displayed when no option is selected
required	`boolean`	Require the field to be completed prior to form submission.
scale	`'condensed' \| 'normal'`	Sets the display size of the input element
selectedIndex (property only)	`number`	The index of the selected option.
selectedOptions (property only)	`@vonage/vivid-api#VwcOptionElement[]`	A collection of the selected options.
shape	`'rounded' \| 'pill'`	Sets the shape of the 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.

Slots

Name	Description
contextual-help	Slot for the contextual-help component, displayed next to the label.
default	Default slot.
helper-text	Describes how to use the select. Alternative to the `helper-text` attribute.
icon	The preferred way to add an icon to the select control.
meta	Slot to add meta content to the select control.

Name	Description
contextual-help	Slot for the contextual-help component, displayed next to the label.
default	Default slot.
helper-text	Describes how to use the select. Alternative to the `helper-text` attribute.
icon	The preferred way to add an icon to the select control.
meta	Slot to add meta content to the select control.

Events

Name	Type	Description
change	`CustomEvent<HTMLElement>`	Fires a custom 'change' event when the value updates
input	`CustomEvent<undefined>`	Fires a custom 'input' event when the value updates

Name	Type	Description
change	`CustomEvent<HTMLElement>`	Fires a custom 'change' event when the value updates
input	`CustomEvent<undefined>`	Fires a custom 'input' event when the value updates

Methods

Name	Params	Returns	Description
checkValidity		`boolean`	Return the current validity of the element.
formResetCallback		`void`
reportValidity		`boolean`	Return the current validity of the element. If false, fires an invalid event at the element.
selectFirstOption		`void`	Moves focus to the first selectable option.
slottedOptionsChanged	`prev: undefined \| Element[]` `next: Element[]`	`void`

option

Properties

Property	Type	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	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.

Slots

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.

Select

Usage

Custom Width

Fixed Dropdown

Open

Slots

Default Slot

Meta Slot

Icon Slot

Helper Text Slot

Contextual Help Slot

CSS Variables

Dropdown Height

API Reference

select

Properties

Slots

Events

Methods

option

Properties

Slots