Vivid Logo Vivid

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

registerSelect('your-prefix');

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.

Fixed Dropdown

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

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.

Slots

Default Slot

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

Meta Slot

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

Icon Slot

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

Helper Text Slot

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

Contextual Help Slot

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

CSS Variables

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

API Reference

select

Properties

Property Type Default 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.
icon IconId A decorative icon the custom element should have. See the [Vivid Icon Gallery](/icons/icons-gallery/) for available icons and `icon-name`s See the Vivid Icon Gallery for available icons: https://icons.vivid.vonage.com/
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#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#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 Default 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 IconId A decorative icon the custom element should have. See the [Vivid Icon Gallery](/icons/icons-gallery/) for available icons and `icon-name`s See the Vivid Icon Gallery for available icons: https://icons.vivid.vonage.com/
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#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#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

Event 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
update:modelValue string Fires when the modelValue value changes
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 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.
icon IconId A decorative icon the custom element should have. See the [Vivid Icon Gallery](/icons/icons-gallery/) for available icons and `icon-name`s See the Vivid Icon Gallery for available icons: https://icons.vivid.vonage.com/
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 IconId A decorative icon the custom element should have. See the [Vivid Icon Gallery](/icons/icons-gallery/) for available icons and `icon-name`s See the Vivid Icon Gallery for available icons: https://icons.vivid.vonage.com/
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.