Select
#

selectcombobox

Select field components are used for collecting user provided information from a list of options. This component opens up a menu for the selection list and action.

Examples
#

Default select
#

Styles
#

Select styles inherit from input styles

Multiple select
#

Includes single or multiple selects.

Decorators
#

Objects as options
#

You can use objects as options. Text will be showing from text-by property from object. Value can be also returned from select using value-by instead of whole object. Comparing object values is done by track-by prop or value-by if it is not provided.
Note: Using text-by without a value-by or track-by may cause inconsistencies in expected behavior.

Value

{ "text": "First", "textBy": "First text by", "value": "1", "valueBy": "first" }

When using Objects as options, it's necessary to utilize track-by because ObjectOptions are compared by object reference by default. track-by allows resolving this comparison by either literal equality.

Track by
#

Track by can be used if you have multiple options with same value.

Value

{ "text": "First", "value": "1", "id": "1" }

Slots
#

Includes option, content, prepend, prepend-inner, append and append-inner slots.

Tagging
#

content slot allows you to overwrite default input element with custom one. So you are able to set tagging state via adding VaChip component:

State
#

Includes error, success, disabled or loading state

Searchable
#

Supports ability to filter option list by typing

Allow create
#

You can add options that initial options do not have

Validation rules
#

Select accepts an array of functions that take an input value as an argument and return either true / false or a string with an error message

Max visible selected options
#

The max-visible-options props sets amount of selected options, that will be shown inside of input wrapper. The rest will be hidden, but may be shown after clicking the badge with hidden options counter.

Displaying selected options at the top of the list
#

The selected-top-shown prop forces to display selected options at the top of the options list.

Autocomplete
#

The autocomplete prop enables autocomplete behavior for the va-select.

Icon-selection
#

The 'iconOption' property allows the addition of custom options to the select dropdown menu, each with an icon and a name.

Accessibility
#

Select has combobox role associated with listbox in dropdown menu. aria-expanded is applied if dropdown is opened. aria-label is set to $t:selectOption if value is selected and $t:noSelectedOption if value is empty. aria-controls is set to combobox-controls-${id}. aria-labelledby is set to input-label-${id}. aria-describedby is set to input-character-count-${id}. aria-activedescendant is set to option-${id}. aria-autocomplete is set to list if autocomplete is enabled. aria-owns is set to combobox-controls-${id}. aria-haspopup is set to listbox. aria-disabled is set to true if select is disabled. aria-required is set to true if select is required. aria-invalid is set to true if select is invalid. aria-multiselectable is set to true if select is multiple. aria-readonly is set to true if select is readonly.

Keyboard navigation
#

By using ARROW DOWN and ARROW UP you can move between options

By using ENTER and SPACE you can select current option

If you type while option list is opened this will create a search buffer (will reset if you do not type for 1 second) that will be used to search in the options labels

API
#

Name	Description	Types	Default
allowCreate	Allow creating new options. Can be set to `unique` if you want to create only unique options	`Boolean \| String`	`false`
anchor		`String \| Object`	-
anchorSelector	Anchor CSS selector instead of passing slot	`String`	`""`
ariaClearLabel	Set aria label for clear button	`String`	`"$t:reset"`
ariaLabel	Set aria label. By default it `$t:selectOption` is value is selected and `$t:noSelectedOption` if value is empty.	`String`	`"$t:select"`
ariaSearchLabel	Set aria label for search input	`String`	`"$t:optionsFilter"`
autocomplete	Enables the autocomplete behaviour.	`Boolean`	`false`
autoPlacement	If dropdown doesn't fit viewport, it will be placed automatically to fit viewport	`Boolean`	`true`
autoSelectFirstOption	Automatically select the first option	`Boolean`	`false`
background	The color name of the background color	`String`	-
clearable	Sets ability to clear selection	`Boolean`	`false`
clearableIcon	Sets the cleaning button icon.	`String`	`"va-clear"`
clearValue	Sets value that should be set after clearing	`String`	`""`
closeOnAnchorClick	Dropdown will be closed when anchor is clicked	`Boolean`	`true`
closeOnChange		`Boolean`	`null`
closeOnClickOutside	Dropdown will be closed when clicked outside dropdown content and anchor	`Boolean`	`true`
closeOnContentClick		`Boolean`	`false`
closeOnFocusOutside		`Boolean`	`true`
color	Color of the component (theme string or `HEX` string).	`String`	`"primary"`
contentClass		`String`	`""`
counter		`Boolean`	-
cursor	Dropdown will be rendered relative to cursor position	`Boolean \| Object`	`false`
delay	Sets throttling delay (ms) for the components any data change (useful for huge data).	`Number`	`0`
dirty	Sets the dirty state of the component	`Boolean`	`false`
disabled	Applies `disabled` style and removes all user interaction effects.	`Boolean`	-
disabledBy	Specify the key in the object to be used as item `disabled` prop. Can be string (path to the key) or function of type: `(option) => option.disabled`	`String \| Function`	`"disabled"`
dropdownIcon	Sets the dropdown icon. Can be object if you want to sets different open/close icons	`String \| Object`	`{ "open": "va-arrow-down", "close": "va-arrow-up" }`
error	Show component in error state.	`Boolean`	-
errorCount	Number of error messages displayed.	`String \| Number`	`1`
errorMessages	Error messages for the component.	`Array \| String`	-
groupBy	When `options` prop is an object, this key will be used to group up options. Can be string (path to the key) or function of type: `(option) => option.group`	`String \| Function`	`"group"`
hideSelected	Sets ability to hide selected options	`Boolean`	`false`
highlightMatchedText	Highlight chars in options that are match the input value (search or autocomplete).	`Boolean`	`true`
hoverOutTimeout	Time in `ms` after mouse leave dropdown before it will be closed	`Number \| String`	`200`
hoverOverTimeout	Time in `ms` after mouse enter dropdown before it will be opened	`Number \| String`	`30`
immediateValidation	Sets the validation to be performed when the component is mounted	`Boolean`	`false`
innerLabel		`Boolean`	`false`
inputAriaDescribedby		`String`	-
inputAriaLabel		`String`	`"$t:inputField"`
inputAriaLabelledby		`String`	-
isContentHoverable	If true, dropdown content will be hoverable	`Boolean`	`true`
isOpen		`Boolean`	-
keepAnchorWidth		`Boolean`	`true`
label	Same as native `label`.	`String`	`""`
loading	Indicates that something is loading (spinner icon).	`Boolean`	`false`
maxHeight	Sets option list maximum height	`String`	`"256px"`
maxLength		`Number \| String`	-
maxSelections	Sets the maximum amount of selected options	`Number \| String`	-
maxVisibleOptions	Max selected options amount, that will be shown inside of input wrapper.	`Number`	`0`
messages	Description messages for the component.	`Array \| String`	`[]`
minSearchChars	Minimal amount of chars in input value to initiate search or autocomplete.	`Number \| String`	`0`
modelValue	The value of the `v-model` bindings.	`String \| Number \| Array \| Object \| Boolean`	-
multiple	Sets select in multiple mode	`Boolean`	`false`
name	Applies `name` to internal input component. Useful for native forms.	`String`	-
noOptionsText	Sets text whom displaying if list have no items	`String`	`"$t:noOptions"`
offset		`Array \| Number`	`[ 1, 0 ]`
options	Available options that the user can select from	`Array`	`[]`
placeholder	Sets the placeholder text to input	`String`	`""`
placement	Sets option list placement. More about placements	`String`	`"bottom"`
preset	Named preset combination of component props.	`String \| Array`	-
readonly	Doesn't look disabled, but acts like one. Mostly useful for wrapper components.	`Boolean`	-
requiredMark	Adds required mark to the label	`Boolean`	`false`
role	Sets the `role` attribute.	`String`	`"button"`
rules	Validation rules .	`Array`	`[]`
search		`String`	-
searchable	Sets ability to filter option list by typing	`Boolean`	`false`
searchPlaceholderText	The text of placeholder of the search input	`String`	`"$t:search"`
selectedTopShown	Selected options will be shown at the top of the options list.	`Boolean`	`false`
separator	Text to separate selected values	`String`	`", "`
stickToEdges	Dropdown will not be rendered outside of viewport. It will be moved in opposite direction.	`Boolean`	`false`
success	Show component in success state.	`Boolean`	`false`
tabindex	Sets the custom `tabindex`.	`String \| Number`	`0`
target	Navigation target, More info here.	`String \| Object`	-
teleport	Element where content will be rendered	`String \| Object`	-
textBy	When `options` prop items are an objects, this key will be used as displayed text. Can be string (path to the key) or function of type: `(option) => option.text`	`String \| Function`	`"text"`
trackBy	When `options` prop items are an objects, this key will be used to track selected `options`. Can be string (path to the key) or function of type: `(option) => option.track`	`String \| Function`	`""`
trigger	Action that will triggered when open and close dropdown.	`String \| Array`	`[ "click", "right-click", "space", "enter" ]`
valueBy	When `options` prop items are an objects, this key will be used as `modelValue`. Can be string (path to the key) or function of type: `(option) => option.value`	`String \| Function`	`""`
verticalScrollOnOverflow		`Boolean`	`true`
virtualScroller	Enables virtual scrolling	`Boolean`	`false`
width	Sets option list width	`String`	`"100%"`

Name	Description
clear	Emitted if select value has been cleared. The event argument is: `any`
createNew	Emitted if search input has created new option
scrollBottom	Emitted once the scroll position of options has reached the bottom. The event argument is: `any`
update:dirty	Fires when the dirty state changes
update:error	Fires when the error state changes
update:errorMessages	Fires when the error messages change
update:isOpen
update:modelValue	The event is triggered when the component needs to change the model. Is also used by `v-model` and must be listed after the `v-model`
update:search	Emitted if search value has changed
updateSearch	Emitted if search value has changed. The event argument is: `any`

Name	Description
append	Adds an item outside the input and after input content
appendInner	Adds an item inside the input and after input content
content	Adds an item instead the input
hiddenOptionsBadge	Replaces default badge with hidden options counter (see `maxVisibleOptions` prop).
hideOptionsButton	Replaces default button for hiding selected options that are over the limit (see `maxVisibleOptions` prop).
option	Allows to specify option template
prepend	Adds an item outside the input and before input content
prependInner	Adds an item inside the input and before input content

Name	Description
reset	Clearing select value

Name	Default Value
--va-select-cursor	pointer
--va-select-dropdown-background	var(--va-background-secondary)
--va-select-state-icon-margin-left	0.25rem

v1.9.0

Now in content slot value is not array in single mode, but array in multiple mode. Use valueArray if you need array value in single/multiple modes
Added option-content slot which is used to show option in dropdown and input
Allow overriding keepAnchorWidth, cloneOnContentClick, triggers, offset props
Fix incorrect search value if model-value is null or undefined
Add slot types
Fix ignored space in autocomplete
Allow null, undefined and '' value to be valid option
Speed up virtual scroll
Autocomplete now uses correct $props.separator instead of ', '

v1.8.0

Select have outlined style by default
solid and bordered props moved to preset="solid" and preset="bordered"

Select
#

Examples
#

Default select
#

Styles
#

Multiple select
#

Decorators
#

Objects as options
#

Track by
#

Slots
#

Tagging
#

State
#

Searchable
#

Allow create
#

Validation rules
#

Max visible selected options
#

Displaying selected options at the top of the list
#

Autocomplete
#

Icon-selection
#

Accessibility
#

Keyboard navigation
#

API
#

Props #

Events #

Slots #

Methods #

Css Variables #

Change log #

Select #

Examples #

Default select #

Styles #

Multiple select #

Decorators #

Objects as options #

Track by #

Slots #

Tagging #

State #

Searchable #

Allow create #

Validation rules #

Max visible selected options #

Displaying selected options at the top of the list #

Autocomplete #

Icon-selection #

Accessibility #

Keyboard navigation #

API #

Props #

Events #

Slots #

Methods #

Css Variables #

Change log #

Select
#

Examples
#

Default select
#

Styles
#

Multiple select
#

Decorators
#

Objects as options
#

Track by
#

Slots
#

Tagging
#

State
#

Searchable
#

Allow create
#

Validation rules
#

Max visible selected options
#

Displaying selected options at the top of the list
#

Autocomplete
#

Icon-selection
#

Accessibility
#

Keyboard navigation
#

API
#