Combobox

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

Usage

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

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

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

registerCombobox('your-prefix');

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

<your-prefix-combobox label="Title" placeholder="Find 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-combobox>

Autocomplete

The autocomplete attribute controls the auto-complete behaviour.

inline means the auto-complete takes place by string matching in the input element
list means the auto-complete takes place by filtering the list in drop down
both means both of the above behaviours take place
none disables the auto-complete behaviour

See aria-autocomplete for more information.

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

<template>
  <VCombobox label="Inline" autocomplete="inline">
    <VOption text="First Option" />
    <VOption text="Second Option" />
  </VCombobox>
  <VCombobox label="List" autocomplete="list">
    <VOption text="First Option" />
    <VOption text="Second Option" />
  </VCombobox>
  <VCombobox label="Both" autocomplete="both">
    <VOption text="First Option" />
    <VOption text="Second Option" />
  </VCombobox>
</template>

<vwc-combobox label="Inline" autocomplete="inline">
  <vwc-option text="First Option"></vwc-option>
  <vwc-option text="Second Option"></vwc-option>
</vwc-combobox>
<vwc-combobox label="List" autocomplete="list">
  <vwc-option text="First Option"></vwc-option>
  <vwc-option text="Second Option"></vwc-option>
</vwc-combobox>
<vwc-combobox label="Both" autocomplete="both">
  <vwc-option text="First Option"></vwc-option>
  <vwc-option text="Second Option"></vwc-option>
</vwc-combobox>

Custom Width

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

You can specify the width of the Combobox using CSS.

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

<template>
  <VCombobox class="vwc-combobox" label="Choose one option">
    <VOption value="1" text="Option 1: dogs" />
    <VOption value="2" text="Option 2: cats" />
    <VOption value="3" text="Option 3: dogs and cats" />
  </VCombobox>
</template>

<style scoped>
.vwc-combobox {
  width: 140px;
}
</style>

<vwc-combobox class="vwc-combobox" label="Choose one 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-combobox>

<style>
  .vwc-combobox {
    width: 140px;
  }
</style>

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

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

<template>
  <VDialog open headline="Dialog Content">
    <template #body>
      <VCombobox autocomplete="both" fixed-dropdown>
        <VOption text="First Option" />
        <VOption text="Second Option" />
        <VOption text="Third Option" />
        <VOption text="Fourth Option" />
      </VCombobox>
    </template>
  </VDialog>
</template>

<vwc-dialog open headline="Dialog Content">
  <div slot="body">
    <vwc-combobox autocomplete="both" fixed-dropdown>
      <vwc-option text="First Option"></vwc-option>
      <vwc-option text="Second Option"></vwc-option>
      <vwc-option text="Third Option"></vwc-option>
      <vwc-option text="Fourth Option"></vwc-option>
    </vwc-combobox>
  </div>
</vwc-dialog>

Open

The open attribute allows the Combobox to be opened programmatically.

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

<template>
  <VCombobox open>
    <VOption text="First Option" />
    <VOption text="Second Option" />
  </VCombobox>
</template>

Value

Set the value attribute to set the default value for the input field.
Setting the property on the element will not change the default value, but will change the value shown in the view as well as the submitted value in a form (imitating the native behavior).

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

<template>
  <VCombobox initialValue="First Option">
    <VOption text="First Option" />
    <VOption text="Second Option" />
  </VCombobox>
</template>

Slots

Default Slot

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

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

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

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

Icon Slot

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

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

<template>
  <VCombobox label="Combobox with custom icon" placeholder="placeholder">
    <template #icon><VIcon name="check-circle-solid" connotation="success" /></template>
    <VOption value="1" text="Option 1" />
    <VOption value="2" text="Option 2" />
  </VCombobox>
</template>

<vwc-combobox label="Combobox with custom icon" placeholder="placeholder">
  <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-combobox>

Meta Slot

Set the meta slot to show meta information after the Combobox text.

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

<template>
  <VCombobox label="Combobox with meta slot" placeholder="placeholder">
    <template #meta><VBadge connotation="success" text="Beta" /></template>
    <VOption value="1" text="Option 1" />
    <VOption value="2" text="Option 2" />
  </VCombobox>
</template>

<vwc-combobox label="Combobox with meta slot" placeholder="placeholder">
  <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-combobox>

Helper Text Slot

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

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

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

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

Contextual Help Slot

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

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

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

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

CSS Variables

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

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

<template>
  <VCombobox aria-label="Options Selector" style="--combobox-height: 200px">
    <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" />
  </VCombobox>
</template>

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

<style>
  vwc-combobox {
    --combobox-height: 200px;
  }
</style>

API Reference

combobox

Properties

Property	Type	Description
appearance	`'fieldset' \| 'ghost'`	Sets the element's appearance
autocomplete	`'none' \| 'inline' \| 'list' \| 'both'`	The autocomplete attribute.
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.
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.
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[]`	A read-only list of options.
placeholder	`string`	Sets the placeholder value of the element, generally used to provide a hint to the user.
placement	`'top' \| 'bottom'`	the placement of the combobox HTML Attribute: string
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 combobox 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
autocomplete	`'none' \| 'inline' \| 'list' \| 'both'`	The autocomplete attribute.
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.
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.
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[]`	A read-only list of options.
placeholder	`string`	Sets the placeholder value of the element, generally used to provide a hint to the user.
placement	`'top' \| 'bottom'`	the placement of the combobox HTML Attribute: string
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 combobox 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 combobox. Alternative to the `helper-text` attribute.
icon	The preferred way to add an icon to the combobox control.
meta	Slot to add meta content to the combobox 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 combobox. Alternative to the `helper-text` attribute.
icon	The preferred way to add an icon to the combobox control.
meta	Slot to add meta content to the combobox control.

Events

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

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

Methods

Name	Returns	Description
checkValidity	`boolean`	Return the current validity of the element.
filterOptions	`void`	Filter available options by text value.
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.
validate	`void`	{@inheritDoc (FormAssociated:interface).validate}

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.

Combobox

Usage

Autocomplete

Custom Width

Fixed-Dropdown

Open

Value

Slots

Default Slot

Icon Slot

Meta Slot

Helper Text Slot

Contextual Help Slot

CSS Variables

Dropdown Height

API Reference

combobox

Properties

Slots

Events

Methods

option

Properties

Slots