Select

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

Labelling

Label Text

The label attribute provides a short description of the purpose of the Select.

If a visible label can’t be used, provide one using the

aria-label

attribute. This ensures screen readers announce the purpose of the element, making it accessible to all users.

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

Helper Text

The helper-text attribute provides additional information about the purpose of the Select.

To add HTML to the helper text, use the helper-text slot.

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

<template>
  <VSelect helper-text="We use this information in to help inform our marketing strategy" label="Where did you hear about us?" placeholder="Select an option" class="marketing">
    <VOption value="friend" text="A friend" />
    <VOption value="net" text="Internet search" />
    <VOption value="online-ad" text="Online advert" />
    <VOption value="radio-ad" text="Radio advert" />
    <VOption value="other" text="Other" />
  </VSelect>
</template>

<style scoped>
.marketing {
  min-inline-size: 250px;
}
</style>

<vwc-select helper-text="We use this information in to help inform our marketing strategy" label="Where did you hear about us?" placeholder="Select an option" class="marketing">
  <vwc-option value="friend" text="A friend"></vwc-option>
  <vwc-option value="net" text="Internet search"></vwc-option>
  <vwc-option value="online-ad" text="Online advert"></vwc-option>
  <vwc-option value="radio-ad" text="Radio advert"></vwc-option>
  <vwc-option value="other" text="Other"></vwc-option>
</vwc-select>

<style>
  .marketing {
    min-inline-size: 250px;
  }
</style>

Placeholder Text

The placeholder attribute provides some text to be displayed when no option has been selected.

Avoid using placeholder text as a substitute for a label. Placeholder text is not a reliable label—it disappears when users type and is not always announced by screen readers. Use a label element to ensure the Combobox is both visually and programmatically associated with a descriptive label.

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

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

<vwc-select placeholder="Select an option" label="Title">
  <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>

Contextual Help

You can add the Contextual Help component using the contextual-help slot. It will be displayed next to the label, providing users additional information.

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

<template>
  <VSelect label="What's your favorite club?" placeholder="Select an option" class="sport">
    <VOption value="friend" text="Ironclad Rovers FC" />
    <VOption value="net" text="Stormhaven United" />
    <VOption value="online-ad" text="Blackpeak Athletic" />
    <VOption value="radio-ad" text="Crimson Harbor FC" />
    <VOption value="other" text="Valewind Wanderers" />
    <template #contextual-help>
      <VContextualHelp>Choose your favorite club</VContextualHelp>
    </template>
  </VSelect>
</template>

<style scoped>
.sport {
  min-inline-size: 250px;
}
</style>

<vwc-select label="What's your favorite club?" placeholder="Select an option" class="sport">
  <vwc-option value="friend" text="Ironclad Rovers FC"></vwc-option>
  <vwc-option value="net" text="Stormhaven United"></vwc-option>
  <vwc-option value="online-ad" text="Blackpeak Athletic"></vwc-option>
  <vwc-option value="radio-ad" text="Crimson Harbor FC"></vwc-option>
  <vwc-option value="other" text="Valewind Wanderers"></vwc-option>
  <vwc-contextual-help slot="contextual-help">Choose your favorite club</vwc-contextual-help>
</vwc-select>

<style>
  .sport {
    min-inline-size: 250px;
  }
</style>

Selected Option

To provide a selected option, use the selected attribute on the selected Option.

<template>
  <VSelect label="Title" class="select">
    <VOption value="mr" text="Mr" defaultSelected />
    <VOption value="mrs" text="Mrs" />
    <VOption value="miss" text="Miss" />
    <VOption value="ms" text="Ms" />
  </VSelect>
</template>
<script setup lang="ts">
import { VSelect, VOption } from '@vonage/vivid-api-vue';
</script>

<vwc-select placeholder="Select an option" label="Title">
  <vwc-option value="mr" text="Mr" selected></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>

Selected Option Label

Use the label attribute on the Option component to proviode a different label to be displayed when the option is selected.

In the example below, the state code is displayed when selected but the full state name is displayed in the option list.

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

<template>
  <VSelect label="US state code" class="state">
    <VOption value="al" text="Alabama" label="AL" defaultSelected />
    <VOption value="ak" text="Alaska" label="AK" />
    <VOption value="az" text="Arizona" label="AZ" />
    <VOption value="ar" text="Arkansas" label="AR" />
    <VOption value="ca" text="California" label="CA" />
  </VSelect>
</template>

<style scoped>
.state {
  min-inline-size: 100px;
}
</style>

<vwc-select placeholder="Select a state" label="US state code" class="state">
  <vwc-option value="al" text="Alabama" label="AL" selected></vwc-option>
  <vwc-option value="ak" text="Alaska" label="AK"></vwc-option>
  <vwc-option value="az" text="Arizona" label="AZ"></vwc-option>
  <vwc-option value="ar" text="Arkansas" label="AR"></vwc-option>
  <vwc-option value="ca" text="California" label="CA"></vwc-option>
</vwc-select>

<style>
  .state {
    min-inline-size: 100px;
  }
</style>

Validation Feedback

Error Text

The error-text attribute provides a custom error message. Any current error state will be overridden by error-text.

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

<template>
  <VSelect error-text="Madrid is incorrect" label="What is the capital of Italy?" class="question" v-model="selectedAnswer">
    <VOption value="madrid" text="Madrid" defaultSelected />
    <VOption value="paris" text="Paris" />
    <VOption value="london" text="London" />
    <VOption value="rome" text="Rome" />
  </VSelect>
</template>

<style scoped>
.question {
  min-inline-size: 250px;
}
</style>

<vwc-select error-text="Madrid is incorrect" placeholder="Select an option" label="What is the capital of Italy?" class="question">
  <vwc-option value="madrid" text="Madrid" selected></vwc-option>
  <vwc-option value="paris" text="Paris"></vwc-option>
  <vwc-option value="london" text="London"></vwc-option>
  <vwc-option value="rome" text="Rome"></vwc-option>
</vwc-select>

<style>
  .question {
    min-inline-size: 250px;
  }
</style>

Success Text

The success-text attribute provides a custom success message. Any current error state will be overridden by success-text.

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

<template>
  <VSelect success-text="Rome is the correct answer" label="What is the capital of Italy?" class="question" v-model="selectedCorrect">
    <VOption value="madrid" text="Madrid" />
    <VOption value="paris" text="Paris" />
    <VOption value="london" text="London" />
    <VOption value="rome" text="Rome" defaultSelected />
  </VSelect>
</template>

<style scoped>
.question {
  min-inline-size: 250px;
}
</style>

<vwc-select success-text="Rome is the correct answer" placeholder="Select an option" label="What is the capital of Italy?" class="question">
  <vwc-option value="madrid" text="Madrid"></vwc-option>
  <vwc-option value="paris" text="Paris"></vwc-option>
  <vwc-option value="london" text="London"></vwc-option>
  <vwc-option value="rome" text="Rome" selected></vwc-option>
</vwc-select>

<style>
  .question {
    min-inline-size: 250px;
  }
</style>

Icon

Use the icon slot to add an icon from the icon library to the component.

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

<template>
  <VSelect label="Results per page" class="results"
    ><template #icon><VIcon name="filter-line" /></template>
    <VOption value="25" text="25 per page" />
    <VOption value="50" text="50 per page" />
    <VOption value="75" text="75 per page" />
    <VOption value="100" text="100 per page" />
  </VSelect>
</template>

<style scoped>
.results {
  inline-size: 190px;
}
</style>

<vwc-select label="Results per page" class="results"
  ><vwc-icon slot="icon" name="filter-line"></vwc-icon>
  <vwc-option value="25" text="25 per page"></vwc-option>
  <vwc-option value="50" text="50 per page"></vwc-option>
  <vwc-option value="75" text="75 per page"></vwc-option>
  <vwc-option value="100" text="100 per page"></vwc-option>
</vwc-select>

<style>
  .results {
    inline-size: 190px;
  }
</style>

Scale

The scale attribute controls the select element display size. Use condensed in situations when space is limited, for example, inside a Data Grid cell.

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

<template>
  <div class="container">
    <VSelect scale="normal" label="Normal" 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>

      <VSelect scale="condensed" label="Condensed" 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>
    </div>

</template>

<style scoped>
.container {
  display: flex;
  gap: 16px;
}
</style>

<div class="container">
  <vwc-select scale="normal" label="Normal" 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>

  <vwc-select scale="condensed" label="Condensed" 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>
</div>

<style>
  .container {
    display: flex;
    gap: 16px;
  }
</style>

The reason for using scale for form elements and not size (as used in other components such as Button), is that size is a HTML attribute that can be used on input elements (and also Text Field) to control the width of the input.

Shape

The shape attribute controls the border radius of the Select input element.

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

<template>
  <div class="container">
    <VSelect shape="rounded" label="Rounded" 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>

      <VSelect shape="pill" label="Pill" 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>
    </div>

</template>

<style scoped>
.container {
  display: flex;
  gap: 16px;
}
</style>

<div class="container">
  <vwc-select shape="rounded" label="Rounded" 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>

  <vwc-select shape="pill" label="Pill" 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>
</div>

<style>
  .container {
    display: flex;
    gap: 16px;
  }
</style>

Appearance

The appearance attribute controls the style of the select element.
Use ghost in combination with a containing element which provides a border, for example when used inside the leading action items slot of Text Field.

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

<template>
  <div class="container">
    <VSelect appearance="fieldset" label="Fieldset" 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>

      <VSelect appearance="ghost" label="Ghost" 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>
    </div>

</template>

<style scoped>
.container {
  display: flex;
  gap: 16px;
}
</style>

<div class="container">
  <vwc-select appearance="fieldset" label="Fieldset" 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>

  <vwc-select appearance="ghost" label="Ghost" 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>
</div>

<style>
  .container {
    display: flex;
    gap: 16px;
  }
</style>

Multiple

The multiple attribute allows the user to select more than one option. When in the multiple selection state, the options will always be visible.

For a better user experience, consider using a Checkbox list or the Searchable Select if there are many options to pick from.

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

<template>
  <VSelect multiple label="Which countries have you visited?" class="countries">
    <VOption value="germany" text="Germany" />
    <VOption value="italy" text="Italy" defaultSelected />
    <VOption value="spain" text="Spain" defaultSelected />
    <VOption value="usa" text="USA" />
  </VSelect>
</template>

<style scoped>
.countries {
  width: 250px;
}
</style>

<vwc-select multiple label="Which countries have you visited?" class="countries">
  <vwc-option value="germany" text="Germany"></vwc-option>
  <vwc-option value="italy" text="Italy" selected></vwc-option>
  <vwc-option value="spain" text="Spain" selected></vwc-option>
  <vwc-option value="usa" text="USA"></vwc-option>
</vwc-select>

<style>
  .countries {
    width: 250px;
  }
</style>

Clearable

The clearable attribute adds a clear button, which clears the selected value(s) when clicked.

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

<template>
  <VSelect clearable 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 clearable 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>

Disabled

The disabled attribute disables the select element.

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

<template>
  <VSelect disabled 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 disabled 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>