Combobox

Combobox contains a free text input for filtering options along with a similar behavior to a Select.

Labelling

Label Text

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

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 { VCombobox, VOption } from '@vonage/vivid-api-vue';
</script>

<template>
  <VCombobox label="Search for something">
    <VOption text="First Option" />
    <VOption text="Second Option" />
  </VCombobox>
</template>

Helper Text

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

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

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

<template>
  <VCombobox 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" />
  </VCombobox>
</template>

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

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

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

Placeholder Text

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

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 { VCombobox, VOption } from '@vonage/vivid-api-vue';
</script>

<template>
  <VCombobox placeholder="placeholder" label="Combobox with placeholder">
    <VOption text="First Option" />
    <VOption text="Second Option" />
  </VCombobox>
</template>

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 { VCombobox, VContextualHelp, VOption } from '@vonage/vivid-api-vue';
</script>

<template>
  <VCombobox 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>
  </VCombobox>
</template>

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

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

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

Validation Feedback

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 { VCombobox, VOption } from '@vonage/vivid-api-vue';
</script>

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

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

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

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

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 { VCombobox, VOption } from '@vonage/vivid-api-vue';
</script>

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

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

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

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

Icon

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

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

const countries = [
{ value: '1', text: 'United States', label: '+1', icon: 'US' },
{ value: '44', text: 'United Kingdom', label: '+44', icon: 'UK' },
{ value: '49', text: 'Germany', label: '+49', icon: 'DE' },
{ value: '355', text: 'Albania', label: '+355', icon: 'AL' },
];

const selectedCountry = ref('');

const selectedIcon = computed(() => {
const country = countries.find((c) => c.text === selectedCountry.value);
return country?.icon || 'search-line';
});

</script>

<template>
  <VCombobox v-model="selectedCountry" label="Country code" class="country-code"
    ><template #icon><VFlag :code="selectedIcon" /></template>
    <VOption v-for="country in countries" :key="country.value" :value="country.value" :text="country.text" :label="country.label">
      <template #icon><VFlag :code="country.icon" /></template>
    </VOption>
  </VCombobox>
</template>

<vwc-combobox label="Country code" class="country-code" id="country-code"
  ><vwc-icon slot="icon" name="search-line"></vwc-icon>
  <vwc-option value="1" text="United States" label="+1"><vwc-flag slot="icon" code="US"></vwc-flag></vwc-option>
  <vwc-option value="44" text="United Kingdom" label="+44"><vwc-flag slot="icon" code="UK"></vwc-flag></vwc-option>
  <vwc-option value="49" text="Germany" label="+49"><vwc-flag slot="icon" code="DE"></vwc-flag></vwc-option>
  <vwc-option value="355" text="Albania" label="+355"><vwc-flag slot="icon" code="AL"></vwc-flag></vwc-option>
</vwc-combobox>

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

Scale

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

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

<template>
  <div class="container">
    <VCombobox 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" />
    </VCombobox>

    <VCombobox 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" />
    </VCombobox>
  </div>
</template>

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

<div class="container">
  <vwc-combobox 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-combobox>

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

</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 Combobox input element.

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

<template>
  <div class="container">
    <VCombobox 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" />
    </VCombobox>

    <VCombobox 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" />
    </VCombobox>
  </div>
</template>

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

<div class="container">
  <vwc-combobox 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-combobox>

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

</div>

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

Appearance

The appearance attribute controls the style of the Combobox 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 { VCombobox, VOption } from '@vonage/vivid-api-vue';
</script>

<template>
  <VCombobox label="fieldset" appearance="fieldset" placeholder="appearance">
    <VOption text="First Option" />
    <VOption text="Second Option" />
  </VCombobox>
  <VCombobox label="ghost" appearance="ghost" placeholder="appearance">
    <VOption text="First Option" />
    <VOption text="Second Option" />
  </VCombobox>
</template>

<vwc-combobox label="fieldset" appearance="fieldset" placeholder="appearance">
  <vwc-option text="First Option"></vwc-option>
  <vwc-option text="Second Option"></vwc-option>
</vwc-combobox>
<vwc-combobox label="ghost" appearance="ghost" placeholder="appearance">
  <vwc-option text="First Option"></vwc-option>
  <vwc-option text="Second Option"></vwc-option>
</vwc-combobox>

Placement

Set the placement attribute to set the combobox’s placement in accordance to its anchor.
Placement options are: top-start , top , top-end , bottom-start (default) , bottom and bottom-end.

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

<template>
  <div class="combobox-wrapper">
    <VCombobox placement="top-start" aria-label="combobox with default placement of bottom-start">
      <VOption text="First Option" />
      <VOption text="Second Option" />
    </VCombobox>
  </div>
</template>

<style scoped>
.combobox-wrapper {
  block-size: 140px;
  display: flex;
  flex-direction: column;
  justify-content: flex-end;
  align-items: start;
}
</style>

<div class="combobox-wrapper">
  <vwc-combobox placement="top-start" aria-label="combobox with default placement of bottom-start">
    <vwc-option text="First Option"></vwc-option>
    <vwc-option text="Second Option"></vwc-option>
  </vwc-combobox>
</div>

<style>
  .combobox-wrapper {
    block-size: 140px;
    display: flex;
    flex-direction: column;
    justify-content: flex-end;
    align-items: start;
  }
</style>

Disabled

The disabled attribute disables the Combobox element.

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

<template>
  <VCombobox disabled label="disabled combobox">
    <VOption text="First Option" />
    <VOption text="Second Option" />
  </VCombobox>
</template>