Combobox Multi-Select | Dialtone Design System

Preview

Usage

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.

Closing the list after selection

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();
  },
}

With Max Selected Validation

Adds validation for max selection. Make sure to provide the following props:

maxSelected the maximum number of selections you can make. 0 is unlimited
maxSelectedMessage should be the message that shown if max selection has been reached

Vue API

import { DtComboboxMultiSelect } from '@dialpad/dialtone-vue';

Slots

Name	Type
`footer`
`header`
`list`

Props

Name	Default	Type
`label` required		`string` String to use for the input label.
`appendTo`	`'body'`	`"'body'"` \| `"'parent'"` \| `"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: `[{"message": string, "type": VALIDATION_MESSAGE_TYPES }]`
`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.

Events

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 `escape` / `enter` instead.
`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

Accessibility

A screen reader visible only close button is added by default.

Keyboard Support

User can navigate between chips pressing the LEFT and RIGHT key.
Pressing LEFT key when you have chips in the input and you are at the start of the text would select the last chip.
Pressing RIGHT key when you are at the last chip would focus on the start of the input.
Pressing BACKSPACE key would focus the chip.
When a chip is focused, pressing BACKSPACE or DELETE key would remove the chip.
User can navigate the popover list pressing UP and DOWN key.

See full Keyboard Support for popover list.

Preview

Usage #

Closing the list after selection #

With Max Selected Validation #

Vue API #

Slots

Props

Events

Accessibility #

Keyboard Support #

Usage

Closing the list after selection

With Max Selected Validation

Vue API

Accessibility

Keyboard Support