MultiSelectComboBox

Description #

<vaadin-multi-select-combo-box> is a web component that wraps <vaadin-combo-box> and extends its functionality to allow selecting multiple items, in addition to basic features.

<vaadin-multi-select-combo-box id="comboBox"></vaadin-multi-select-combo-box>

const comboBox = document.querySelector('#comboBox');
comboBox.items = ['apple', 'banana', 'lemon', 'orange'];
comboBox.selectedItems = ['lemon', 'orange'];

Styling #

The following shadow DOM parts are available for styling:

Part name	Description
chips	The element that wraps slotted chips for selected items
label	The label element
input-field	The element that wraps prefix, value and suffix
clear-button	The clear button
error-message	The error message element
helper-text	The helper text element wrapper
required-indicator	The required state indicator element
toggle-button	The toggle button
overlay	The overlay container
content	The overlay content
loader	The loading indicator shown while loading items

The following state attributes are available for styling:

Attribute	Description
disabled	Set to a disabled element
has-value	Set when the element has a value
has-label	Set when the element has a label
has-helper	Set when the element has helper text or slot
has-error-message	Set when the element has an error message
invalid	Set when the element is invalid
focused	Set when the element is focused
focus-ring	Set when the element is keyboard focused
loading	Set when loading items from the data provider
opened	Set when the dropdown is open
readonly	Set to a readonly element

The following custom CSS properties are available for styling:

Custom property	Description	Default
--vaadin-field-default-width	Default width of the field	12em
--vaadin-multi-select-combo-box-overlay-width	Width of the overlay	auto
--vaadin-multi-select-combo-box-overlay-max-height	Max height of the overlay	65vh
--vaadin-multi-select-combo-box-input-min-width	Min width of the input	4em

Internal components #

In addition to <vaadin-multi-select-combo-box> itself, the following internal components are themable:

• <vaadin-multi-select-combo-box-chip>
• <vaadin-multi-select-combo-box-item> - has the same API as <vaadin-item>.

See Styling Components documentation.

Properties #

accessibleName #

Type: string | null | undefined

String used to label the component to screen reader users.

accessibleNameRef #

Type: string | null | undefined

Id of the element used as label of the component to screen reader users.

allowCustomValue #

Type: boolean

When true, the user can input a value that is not present in the items list.

allowedCharPattern #

Type: string

A pattern matched against individual characters the user inputs.

When set, the field will prevent:

• keydown events if the entered key doesn't match /^allowedCharPattern$/
• paste events if the pasted text doesn't match /^allowedCharPattern*$/
• drop events if the dropped text doesn't match /^allowedCharPattern*$/

For example, to allow entering only numbers and minus signs, use: allowedCharPattern = "[\\d-]"

autoExpandHorizontally #

Type: boolean

Set to true to auto expand horizontally, causing input field to grow until max width is reached.

autoExpandVertically #

Type: boolean

Set to true to not collapse selected items chips into the overflow chip and instead always expand vertically, causing input field to wrap into multiple lines when width is limited.

autofocus #

Type: boolean

Specify that this control should have input focus when the page loads.

autoOpenDisabled #

Type: boolean | null | undefined

Set true to prevent the overlay from opening automatically.

autoselect #

Type: boolean

If true, the input text gets fully selected when the field is focused using click or touch / tap.

clearButtonVisible #

Type: boolean

Set to true to display the clear icon which clears the input.

It is up to the component to choose where to place the clear icon: in the Shadow DOM or in the light DOM. In any way, a reference to the clear icon element should be provided via the clearElement getter.

dataProvider #

Type: ComboBoxDataProvider<any> | null | undefined

Function that provides items lazily. Receives arguments params, callback

params.page Requested page index

params.pageSize Current page size

params.filter Currently applied filter

callback(items, size) Callback function with arguments:

• items Current page of items
• size Total number of items.

See also: ComboBoxDataProvider

disabled #

Type: boolean

If true, the user cannot interact with this element.

errorMessage #

Type: string | null | undefined

Error to show when the field is invalid.

filter #

Type: string

Filtering string the user has typed into the input field.

filteredItems #

Type: any[] | undefined

A subset of items, filtered based on the user input. Filtered items can be assigned directly to omit the internal filtering functionality. The items can be of either String or Object type.

helperText #

Type: string | null | undefined

String used for the helper text.

i18n #

Type: MultiSelectComboBoxI18n

The object used to localize this component. To change the default localization, replace the entire i18n object or just the property you want to modify.

The object has the following JSON structure and default values:

{
  // Screen reader announcement on clear button click.
  cleared: 'Selection cleared',
  // Screen reader announcement when a chip is focused.
  focused: ' focused. Press Backspace to remove',
  // Screen reader announcement when item is selected.
  selected: 'added to selection',
  // Screen reader announcement when item is deselected.
  deselected: 'removed from selection',
  // Screen reader announcement of the selected items count.
  // {count} is replaced with the actual count of items.
  total: '{count} items selected',
}

See also: MultiSelectComboBoxI18n

invalid #

Type: boolean

Set to true when the field is invalid.

itemClassNameGenerator #

Type: (item: any) => string

A function used to generate CSS class names for dropdown items and selected chips based on the item. The return value should be the generated class name as a string, or multiple class names separated by whitespace characters.

itemIdPath #

Type: string

Path for the id of the item, used to detect whether the item is selected.

itemLabelPath #

Type: string

Path for label of the item. If items is an array of objects, the itemLabelPath is used to fetch the displayed string label for each item.

The item label is also used for matching items when processing user input, i.e., for filtering and selecting items.

items #

Type: any[] | undefined

A full set of items to filter the visible options from. The items can be of either String or Object type.

itemValuePath #

Type: string

Path for the value of the item. If items is an array of objects, the itemValuePath: is used to fetch the string value for the selected item.

The item value is used in the value property of the combo box, to provide the form value.

keepFilter #

Type: boolean

When true, filter string isn't cleared after selecting an item.

label #

Type: string | null | undefined

The label text for the input node. When no light dom defined via [slot=label], this value will be used.

loading #

Type: boolean

True when loading items from the data provider, false otherwise.

manualValidation #

Type: boolean

Set to true to enable manual validation mode. This mode disables automatic constraint validation, allowing you to control the validation process yourself. You can still trigger constraint validation manually with the validate() method or use checkValidity() to assess the component's validity without affecting the invalid state. In manual validation mode, you can also manipulate the invalid property directly through your application logic without conflicts with the component's internal validation.

name #

Type: string

The name of this field.

opened #

Type: boolean

True if the dropdown is open, false otherwise.

pageSize #

Type: number

Number of items fetched at a time from the dataprovider.

placeholder #

Type: string

A hint to the user of what can be entered in the control. The placeholder will be only displayed in the case when there is no item selected.

readonly #

Type: boolean

When present, it specifies that the field is read-only.

renderer #

Type: MultiSelectComboBoxRenderer<any> | null | undefined

Custom function for rendering the content of every item. Receives three arguments:

• root The <vaadin-multi-select-combo-box-item> internal container DOM element.
• comboBox The reference to the <vaadin-multi-select-combo-box> element.
• model The object with the properties related with the rendered item, contains:
  • model.index The index of the rendered item.
  • model.item The item.

See also: MultiSelectComboBoxRenderer

required #

Type: boolean

Specifies that the user must fill in a value.

selectedItems #

Type: any[]

The list of selected items. Note: modifying the selected items creates a new array each time.

selectedItemsOnTop #

Type: boolean

Set to true to group selected items at the top of the overlay.

size #

Type: number | undefined

Total number of items.

title #

Type: string

The text usually displayed in a tooltip popup when the mouse is over the field.

Methods #

checkValidity #

Type: () => boolean

Returns true if the current input value satisfies all constraints (if any).

clear #

Type: () => void

Clears the selected items.

clearCache #

Type: () => void

Clears the cached pages and reloads data from data provider when needed.

close #

Type: () => void

Closes the dropdown list.

open #

Type: () => void

Opens the dropdown list.

requestContentUpdate #

Type: () => void

Requests an update for the content of items. While performing the update, it invokes the renderer (passed in the renderer property) once an item.

It is not guaranteed that the update happens immediately (synchronously) after it is requested.

validate #

Type: () => boolean

Validates the field and sets the invalid property based on the result.

The method fires a validated event with the result of the validation.

Events #

change #

Type: MultiSelectComboBoxChangeEvent

Fired when the user commits a value change.

custom-value-set #

Type: MultiSelectComboBoxCustomValueSetEvent

Fired when the user sets a custom value.

filter-changed #

Type: MultiSelectComboBoxFilterChangedEvent

Fired when the filter property changes.

input #

Type: CustomEvent

Fired when the value is changed by the user: on every typing keystroke, and the value is cleared using the clear button.

invalid-changed #

Type: MultiSelectComboBoxInvalidChangedEvent

Fired when the invalid property changes.

opened-changed #

Type: MultiSelectComboBoxOpenedChangedEvent

Fired when the opened property changes.

selected-items-changed #

Type: MultiSelectComboBoxSelectedItemsChangedEvent

Fired when the selectedItems property changes.

validated #

Type: MultiSelectComboBoxValidatedEvent

Fired whenever the field is validated.

Types #

ComboBoxDataProvider #

export type ComboBoxDataProvider<TItem> = (
  params: ComboBoxDataProviderParams,
  callback: ComboBoxDataProviderCallback<TItem>,
) => void;

ComboBoxDataProviderCallback #

export type ComboBoxDataProviderCallback<TItem> = (items: TItem[], size?: number) => void;

ComboBoxDataProviderParams #

export interface ComboBoxDataProviderParams {
  page: number;
  pageSize: number;
  filter: string;
}

ComboBoxItemModel #

export interface ComboBoxItemModel<TItem> {
  index: number;
  item: TItem;
  selected: boolean;
  focused: boolean;
}

MultiSelectComboBoxChangeEvent #

/**
 * Fired when the user commits a value change.
 */
export type MultiSelectComboBoxChangeEvent<TItem> = Event & {
  target: MultiSelectComboBox<TItem>;
};

MultiSelectComboBoxCustomValueSetEvent #

/**
 * Fired when the user sets a custom value.
 */
export type MultiSelectComboBoxCustomValueSetEvent = CustomEvent<string>;

MultiSelectComboBoxFilterChangedEvent #

/**
 * Fired when the `filter` property changes.
 */
export type MultiSelectComboBoxFilterChangedEvent = CustomEvent<{ value: string }>;

MultiSelectComboBoxI18n #

export interface MultiSelectComboBoxI18n {
  cleared: string;
  focused: string;
  selected: string;
  deselected: string;
  total: string;
}

MultiSelectComboBoxInvalidChangedEvent #

/**
 * Fired when the `invalid` property changes.
 */
export type MultiSelectComboBoxInvalidChangedEvent = CustomEvent<{ value: boolean }>;

MultiSelectComboBoxOpenedChangedEvent #

/**
 * Fired when the `opened` property changes.
 */
export type MultiSelectComboBoxOpenedChangedEvent = CustomEvent<{ value: boolean }>;

MultiSelectComboBoxRenderer #

export type MultiSelectComboBoxRenderer<TItem> = (
  root: HTMLElement,
  comboBox: MultiSelectComboBox<TItem>,
  model: ComboBoxItemModel<TItem>,
) => void;

MultiSelectComboBoxSelectedItemsChangedEvent #

/**
 * Fired when the `selectedItems` property changes.
 */
export type MultiSelectComboBoxSelectedItemsChangedEvent<TItem> = CustomEvent<{ value: TItem[] }>;

MultiSelectComboBoxValidatedEvent #

/**
 * Fired whenever the field is validated.
 */
export type MultiSelectComboBoxValidatedEvent = CustomEvent<{ valid: boolean }>;