<dt-combobox-multi-select ref="comboboxMultiSelect" label="Label Text" :selected-items="selectedItems" @update:model-value="onInput" @select="onSelect" @remove="onRemove" > <template #list> <dt-stack as="ul" class="d-ps-relative d-m-50 d-px-0"> <dt-list-item v-for="(item, i) in items" :key="item.id" role="option" navigation-type="arrow-keys" @click="onSelect(i)" > {{ item.value }} <template #right> <span class="d-fc-secondary">{{ item.type }}</span> </template> </dt-list-item> </dt-stack> </template> </dt-combobox-multi-select>
The Combobox Multi-Select component combines an input element with a dropdown list, allowing users to select multiple items. Selected items appear as chips within the input field. It is commonly used for multi-select user pickers where selected items display avatars alongside names — for example, selecting team members, recipients, or participants with avatar chips.
When not passing showList and hasSuggestionList is true, to close the list with the select event, use the closeComboboxList method:
methods: {
onSelect (i) {
this.$refs.comboboxMultiSelect.closeComboboxList();
},
}
Adds validation for max selection. Make sure to provide the following props:
maxSelected the maximum number of selections you can make. 0 is unlimitedmaxSelectedMessage should be the message that shown if max selection has been reached<dt-combobox-multi-select ref="comboboxMultiSelect" label="Label Text" description="Select up to 2 options." :selected-items="selectedItems" :max-selected="2" :max-selected-message="[{ message: 'More than 2 selected', type: 'critical' }]" @update:model-value="onInput" @select="onSelect" @remove="onRemove" @max-selected="onMaxSelected" > <template #list> <dt-stack as="ul" class="d-ps-relative d-m-50 d-px-0"> <dt-list-item v-for="(item, i) in items" :key="item.id" role="option" navigation-type="arrow-keys" @click="onSelect(i)" > {{ item.value }} <template #right> <span class="d-fc-secondary">{{ item.type }}</span> </template> </dt-list-item> </dt-stack> </template> </dt-combobox-multi-select>
A screen reader visible only close button is added by default.
LEFT and RIGHT key.LEFT key when you have chips in the input and you are at the start of the text would select the last chip.RIGHT key when you are at the last chip would focus on the start of the input.BACKSPACE key would focus the chip.BACKSPACE or DELETE key would remove the chip.UP and DOWN key.See full Keyboard Support for popover list.
import { DtComboboxMultiSelect } from '@dialpad/dialtone-vue';
Name
|
Type
|
|---|---|
footer | |
header | |
list |
Name
|
Default
|
Type
|
|---|---|---|
label
required
| string String to use for the input label. | |
appendTo | 'body' |
"'body'"
|
"'parent'"
|
"'root'"
|
"HTMLElement"
|
""
Sets the element to which the popover is going to append to.
'body' will append to the nearest body (supports shadow DOM). |
chipMaxWidth | '' | string Determines the maximum width of a single chip. If the text within this chip exceeds the value
it will be truncated with ellipses.
Possible units rem|px|em |
collapseOnFocusOut | false | boolean Determines whether the combobox should collapse to a single when losing focus. |
description | '' | string Description for the input |
dialogClass | '' | string|object|array Additional class for the popover dialog element. |
disabled | false | boolean When true, disables the underlying input. |
footerClass | '' | string|array|object Additional class name for the footer wrapper element. |
hasSuggestionList | true | boolean Displays the list when the combobox is focused, before the user has typed anything.
When this is enabled the list will not close after selection. |
headerClass | '' | string|array|object Additional class name for the header wrapper element. |
inputClass | '' | string|object|array Additional class name for the input element.
Can accept String, Object, and Array, i.e. has the
same API as Vue's built-in handling of the class attribute. |
inputMessages | [] | array Input validation messages |
inputWrapperClass | '' | string|object|array Additional class name for the input wrapper element.
Can accept all of String, Object, and Array, i.e. has the
same api as Vue's built-in handling of the class attribute. |
listClass | '' | string|array|object Additional class name for the list wrapper element. |
listMaxHeight | '300px' | string Determines maximum height for the popover before overflow.
Possible units rem|px|em |
listMaxWidth | '' | string Determines maximum width for the popover before overflow.
Possible units rem|px|em |
loading | false | boolean Determines if the list is loading |
loadingMessage | 'loading...' | string The message when the list is loading |
maxSelected | 0 | number Would be the maximum number of selections you can make. 0 is unlimited |
maxSelectedMessage | [] | array Max select message when the max selections is exceeded with the structure:
|
placeholder | 'Select one or start typing' | string Input placeholder |
reservedRightSpace | 64 | number Amount of reserved space (in px) on the right side of the input
before the chips and the input caret jump to the next line.
default is 64 |
selectedItems | [] | array The selected items |
showInputMessages | true | boolean Show input validation message |
showLabel | true |
"true"
|
"false"
Determines visibility of input label. |
showList | null | boolean Determines when to show the list element and also controls the aria-expanded attribute.
Leaving this null will have the combobox trigger on input focus by default.
If you set this value, the default trigger behavior will be disabled and you can
control it as you need. |
size | 300 |
"100"
|
"200"
|
"300"
Size of the chip. |
transition | 'fade' | string Named transition when the content display is toggled. |
Name
|
Type
|
|---|---|
chip-keydown | KeyboardEvent Native keydown event fired when a key is pressed while a chip is focused. |
combobox-highlight | Object Event fired when combobox item is highlighted |
enter | KeyboardEvent Fired when Enter is pressed in the text input.
Not fired when a chip is focused. |
escape | KeyboardEvent Fired when Escape is pressed in the text input.
Not fired when a chip is focused. |
keydown | KeyboardEvent Native keydown event fired when a key is pressed in the text input.
For the common Escape and Enter cases, listen to |
max-selected | Object Event fired when max selected items limit is reached |
remove | String Event fired when item removed |
select | Number Event fired when item selected |
update:modelValue | String Event fired to sync the modelValue prop with the parent component |
Combobox Multi-Select documentation last updated Friday, September 4, 2026
fix/popover-modal-zindex-scope