Package com.vaadin.flow.component.combobox

Class MultiSelectComboBox<TItem>

java.lang.Object

com.vaadin.flow.component.Component

com.vaadin.flow.component.AbstractField<C,T>

com.vaadin.flow.component.AbstractSinglePropertyField<TComponent,TValue>

com.vaadin.flow.component.combobox.ComboBoxBase<MultiSelectComboBox<TItem>,TItem,Set<TItem>>

com.vaadin.flow.component.combobox.MultiSelectComboBox<TItem>

Type Parameters:

TItem - the type of the items to be selectable from the combo box

All Implemented Interfaces:

AttachNotifier, BlurNotifier<MultiSelectComboBox<TItem>>, DetachNotifier, Focusable<MultiSelectComboBox<TItem>>, FocusNotifier<MultiSelectComboBox<TItem>>, HasElement, HasEnabled, HasHelper, HasLabel, HasSize, HasStyle, HasTheme, HasValidation, HasValue<AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>, HasValueAndElement<AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>, HasAllowedCharPattern, HasClearButton, HasThemeVariant<MultiSelectComboBoxVariant>, HasTooltip, HasValidator<Set<TItem>>, HasDataView<TItem,String,ComboBoxDataView<TItem>>, HasLazyDataView<TItem,String,ComboBoxLazyDataView<TItem>>, HasListDataView<TItem,ComboBoxListDataView<TItem>>, MultiSelect<MultiSelectComboBox<TItem>,TItem>, Serializable

@Tag("vaadin-multi-select-combo-box")
@NpmPackage(value="@vaadin/polymer-legacy-adapter",version="23.4.0") @NpmPackage(value="@vaadin/multi-select-combo-box",version="23.4.0")
@JsModule("@vaadin/polymer-legacy-adapter/style-modules.js") @JsModule("@vaadin/multi-select-combo-box/src/vaadin-multi-select-combo-box.js") @JsModule("@vaadin/polymer-legacy-adapter/template-renderer.js") @JsModule("./flow-component-renderer.js") @JsModule("./comboBoxConnector.js")
public class MultiSelectComboBox<TItem>
extends ComboBoxBase<MultiSelectComboBox<TItem>,TItem,Set<TItem>>
implements MultiSelect<MultiSelectComboBox<TItem>,TItem>, HasThemeVariant<MultiSelectComboBoxVariant>

MultiSelectComboBox allows the user to select one or more values from a filterable list of options presented in an overlay. Compared to ComboBox, MultiSelectComboBox allows to select multiple values.

MultiSelectComboBox supports lazy loading. This means that when using large data sets, items are requested from the server one "page" at a time when the user scrolls down the overlay. The number of items in one page is by default 50, and can be changed with ComboBoxBase.setPageSize(int).

MultiSelectComboBox can do filtering either in the browser or in the server. When MultiSelectComboBox has only a relatively small set of items, the filtering will happen in the browser, allowing smooth user-experience. When the size of the data set is larger than the pageSize, the webcomponent doesn't necessarily have all the data available, and it will make requests to the server to handle the filtering. Also, if you have defined custom filtering logic, with eg. ComboBoxBase.setItems(ComboBox.ItemFilter, Collection), filtering will happen in the server. To enable client-side filtering with larger data sets, you can override the pageSize to be bigger than the size of your data set. However, then the full data set will be sent to the client immediately, and you will lose the benefits of lazy loading.

Author:

Vaadin Ltd

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	MultiSelectComboBox.AutoExpandMode	Defines possible behavior of the component when not all selected items can be displayed as chips within the current field width.

Nested classes/interfaces inherited from class com.vaadin.flow.component.combobox.ComboBoxBase

ComboBoxBase.CustomValueSetEvent<TComponent extends ComboBoxBase<TComponent,?,?>>

Nested classes/interfaces inherited from class com.vaadin.flow.component.AbstractField

AbstractField.ComponentValueChangeEvent<C extends Component,V>

Nested classes/interfaces inherited from interface com.vaadin.flow.component.BlurNotifier

BlurNotifier.BlurEvent<C extends Component>

Nested classes/interfaces inherited from interface com.vaadin.flow.component.FocusNotifier

FocusNotifier.FocusEvent<C extends Component>

Nested classes/interfaces inherited from interface com.vaadin.flow.component.HasValue

HasValue.ValueChangeEvent<V>, HasValue.ValueChangeListener<E extends HasValue.ValueChangeEvent<?>>

Constructor Summary

Constructors

Constructor	Description
MultiSelectComboBox()	Default constructor.
MultiSelectComboBox(int pageSize)	Creates an empty combo box with the defined page size for lazy loading.
MultiSelectComboBox(HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>> listener)	Constructs a combo box with a value change listener.
MultiSelectComboBox(String label)	Creates an empty combo box with the defined label.
MultiSelectComboBox(String label, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>> listener)	Constructs a combo box with the defined label and a value change listener.
MultiSelectComboBox(String label, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>> listener, TItem... items)	Constructs a combo box with the defined label, a value change listener and populated with the items in the array.
MultiSelectComboBox(String label, Collection<TItem> items)	Creates a combo box with the defined label and populated with the items in the collection.
MultiSelectComboBox(String label, TItem... items)	Creates a combo box with the defined label and populated with the items in the array.

Method Summary

Modifier and Type	Method	Description
Registration	addSelectionListener(MultiSelectionListener<MultiSelectComboBox<TItem>,TItem> listener)	Adds a selection listener that will be called when the selection is changed either by the user or programmatically.
MultiSelectComboBox.AutoExpandMode	getAutoExpand()	Gets the behavior of the component when not all selected items can be displayed as chips within the current field width.
MultiSelectComboBoxI18n	getI18n()	Gets the internationalization object previously set for this component.
Set<TItem>	getSelectedItems()	Returns an immutable set of the currently selected items.
Set<TItem>	getValue()	Gets the value of the component, which is a set of selected items.
boolean	isKeepFilter()	Gets whether the filter is kept after selecting items.
boolean	isSelected(TItem item)	Whether the item is currently selected in the combo box.
boolean	isSelectedItemsOnTop()	Gets whether selected items are grouped at the top of the overlay.
protected void	onAttach(AttachEvent attachEvent)	Called when the component is attached to a UI.
protected void	refreshValue()	Refresh value / selection of the web component after changes that might affect the presentation / rendering of items
void	setAutoExpand(MultiSelectComboBox.AutoExpandMode autoExpandMode)	Sets the behavior of the component when not all selected items can be displayed as chips within the current field width.
void	setI18n(MultiSelectComboBoxI18n i18n)	Sets the internationalization properties for this component.
void	setKeepFilter(boolean keepFilter)	Enables or disables keeping the filter after selecting items.
void	setSelectedItemsOnTop(boolean selectedItemsOnTop)	Enables or disables grouping of the selected items at the top of the overlay.
void	setValue(Collection<TItem> items)	Sets the value of the component, which is a set of selected items.
void	setValue(Set<TItem> value)	Sets the value of the component, which is a set of selected items.
void	setValue(TItem... items)	Sets the value of the component, which is a set of selected items.
void	updateSelection(Set<TItem> addedItems, Set<TItem> removedItems)	Updates the selection by adding and removing the given items from it.

Methods inherited from class com.vaadin.flow.component.combobox.ComboBoxBase

addCustomValueSetListener, generateLabel, getDataCommunicator, getDataController, getDataGenerator, getDataProvider, getErrorMessage, getFilter, getGenericDataView, getItemLabelGenerator, getKeyMapper, getLazyDataView, getListDataView, getPageSize, getPlaceholder, getRenderManager, isAllowCustomValue, isAutofocus, isAutoOpen, isInvalid, isOpened, isRequired, onDetach, runBeforeClientResponse, setAllowCustomValue, setAutofocus, setAutoOpen, setDataProvider, setDataProvider, setDataProvider, setDataProvider, setDataProvider, setErrorMessage, setFilter, setInvalid, setItemLabelGenerator, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItemsWithFilterConverter, setItemsWithFilterConverter, setOpened, setPageSize, setPlaceholder, setRenderer, setRequired, setRequiredIndicatorVisible, validate

Methods inherited from class com.vaadin.flow.component.AbstractSinglePropertyField

getSynchronizationRegistration, hasValidValue, setPresentationValue, setSynchronizedEvent

Methods inherited from class com.vaadin.flow.component.AbstractField

addValueChangeListener, getEmptyValue, isEmpty, setModelValue, valueEquals

Methods inherited from class com.vaadin.flow.component.Component

addListener, findAncestor, fireEvent, from, get, getChildren, getElement, getEventBus, getId, getListeners, getLocale, getParent, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onEnabledStateChanged, scrollIntoView, set, setElement, setId, setVisible

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.vaadin.flow.component.AttachNotifier

addAttachListener

Methods inherited from interface com.vaadin.flow.component.BlurNotifier

addBlurListener

Methods inherited from interface com.vaadin.flow.component.DetachNotifier

addDetachListener

Methods inherited from interface com.vaadin.flow.component.Focusable

addFocusShortcut, blur, focus, getTabIndex, setTabIndex

Methods inherited from interface com.vaadin.flow.component.FocusNotifier

addFocusListener

Methods inherited from interface com.vaadin.flow.component.shared.HasAllowedCharPattern

getAllowedCharPattern, setAllowedCharPattern

Methods inherited from interface com.vaadin.flow.component.shared.HasClearButton

isClearButtonVisible, setClearButtonVisible

Methods inherited from interface com.vaadin.flow.component.HasElement

getElement

Methods inherited from interface com.vaadin.flow.component.HasEnabled

isEnabled, setEnabled

Methods inherited from interface com.vaadin.flow.component.HasHelper

getHelperComponent, getHelperText, setHelperComponent, setHelperText

Methods inherited from interface com.vaadin.flow.component.HasLabel

getLabel, setLabel

Methods inherited from interface com.vaadin.flow.data.provider.HasListDataView

setItems

Methods inherited from interface com.vaadin.flow.component.HasSize

getHeight, getHeightUnit, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getWidth, getWidthUnit, setHeight, setHeight, setHeightFull, setMaxHeight, setMaxHeight, setMaxWidth, setMaxWidth, setMinHeight, setMinHeight, setMinWidth, setMinWidth, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthFull

Methods inherited from interface com.vaadin.flow.component.HasStyle

addClassName, addClassNames, getClassName, getClassNames, getStyle, hasClassName, removeClassName, removeClassNames, setClassName, setClassName

Methods inherited from interface com.vaadin.flow.component.HasTheme

addThemeName, addThemeNames, getThemeName, getThemeNames, hasThemeName, removeThemeName, removeThemeNames, setThemeName, setThemeName

Methods inherited from interface com.vaadin.flow.component.shared.HasThemeVariant

addThemeVariants, removeThemeVariants

Methods inherited from interface com.vaadin.flow.component.shared.HasTooltip

getTooltip, setTooltipText

Methods inherited from interface com.vaadin.flow.data.binder.HasValidator

addValidationStatusChangeListener, getDefaultValidator

Methods inherited from interface com.vaadin.flow.component.HasValue

addValueChangeListener, clear, getOptionalValue, isEmpty

Methods inherited from interface com.vaadin.flow.component.HasValueAndElement

isReadOnly, isRequiredIndicatorVisible, setReadOnly, setRequiredIndicatorVisible

Methods inherited from interface com.vaadin.flow.data.selection.MultiSelect

deselect, deselect, deselectAll, getEmptyValue, select, select

Constructor Detail

MultiSelectComboBox

public MultiSelectComboBox()

Default constructor. Creates an empty combo box.

MultiSelectComboBox

public MultiSelectComboBox(int pageSize)

Creates an empty combo box with the defined page size for lazy loading.

The default page size is 50.

The page size is also the largest number of items that can support client-side filtering. If you provide more items than the page size, the component has to fall back to server-side filtering.

Parameters:

pageSize - the amount of items to request at a time for lazy loading

See Also:

ComboBoxBase.setPageSize(int)

MultiSelectComboBox

public MultiSelectComboBox(String label)

Creates an empty combo box with the defined label.

Parameters:

label - the label describing the combo box

See Also:

HasLabel.setLabel(String)

MultiSelectComboBox

public MultiSelectComboBox(String label,
                           Collection<TItem> items)

Creates a combo box with the defined label and populated with the items in the collection.

Parameters:

label - the label describing the combo box

items - the items to be shown in the list of the combo box

See Also:

HasLabel.setLabel(String), ComboBoxBase.setItems(Collection)

MultiSelectComboBox

@SafeVarargs
public MultiSelectComboBox(String label,
                           TItem... items)

Creates a combo box with the defined label and populated with the items in the array.

Parameters:

label - the label describing the combo box

items - the items to be shown in the list of the combo box

See Also:

HasLabel.setLabel(String), HasListDataView.setItems(Object...)

MultiSelectComboBox

public MultiSelectComboBox(HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>> listener)

Constructs a combo box with a value change listener.

Parameters:

listener - the value change listener to add

See Also:

AbstractField.addValueChangeListener(ValueChangeListener)

MultiSelectComboBox

public MultiSelectComboBox(String label,
                           HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>> listener)

Constructs a combo box with the defined label and a value change listener.

Parameters:

label - the label describing the combo box

listener - the value change listener to add

See Also:

HasLabel.setLabel(String), AbstractField.addValueChangeListener(ValueChangeListener)

MultiSelectComboBox

@SafeVarargs
public MultiSelectComboBox(String label,
                           HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>> listener,
                           TItem... items)

Constructs a combo box with the defined label, a value change listener and populated with the items in the array.

Parameters:

label - the label describing the combo box

listener - the value change listener to add

items - the items to be shown in the list of the combo box

See Also:

HasLabel.setLabel(String), AbstractField.addValueChangeListener(ValueChangeListener), HasListDataView.setItems(Object...)

Method Detail

onAttach

protected void onAttach(AttachEvent attachEvent)

Description copied from class: Component

Called when the component is attached to a UI.

The default implementation does nothing.

This method is invoked before the AttachEvent is fired for the component.

Overrides:

onAttach in class ComboBoxBase<MultiSelectComboBox<TItem>,TItem,Set<TItem>>

Parameters:

attachEvent - the attach event

getValue

public Set<TItem> getValue()

Gets the value of the component, which is a set of selected items.

The returned set is immutable and can not be modified. Use MultiSelect.select(Object[]) or MultiSelect.deselect(Object[]) to add or remove individual items.

Specified by:

getValue in interface HasValue<AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>

Specified by:

getValue in interface MultiSelect<MultiSelectComboBox<TItem>,TItem>

Overrides:

getValue in class AbstractField<MultiSelectComboBox<TItem>,Set<TItem>>

Returns:

an unmodifiable set of selected items

setValue

public void setValue(Set<TItem> value)

Sets the value of the component, which is a set of selected items.

Note that it is allowed to pass null as value to clear the selection, but that an empty set will be stored as value instead.

Specified by:

setValue in interface HasValue<AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>

Specified by:

setValue in interface MultiSelect<MultiSelectComboBox<TItem>,TItem>

Overrides:

setValue in class ComboBoxBase<MultiSelectComboBox<TItem>,TItem,Set<TItem>>

Parameters:

value - the new value

setValue

@SafeVarargs
public final void setValue(TItem... items)

Sets the value of the component, which is a set of selected items. As each item can only be selected once, duplicates in the provided items will be removed. Passing no items will result in an empty selection.

Parameters:

items - the new value

setValue

public void setValue(Collection<TItem> items)

Sets the value of the component, which is a set of selected items. As each item can only be selected once, duplicates in the provided items will be removed. Passing no items will result in an empty selection.

Parameters:

items - the new value

refreshValue

protected void refreshValue()

Description copied from class: ComboBoxBase

Refresh value / selection of the web component after changes that might affect the presentation / rendering of items

Specified by:

refreshValue in class ComboBoxBase<MultiSelectComboBox<TItem>,TItem,Set<TItem>>

isSelected

public boolean isSelected(TItem item)

Description copied from class: ComboBoxBase

Whether the item is currently selected in the combo box.

Specified by:

isSelected in interface MultiSelect<MultiSelectComboBox<TItem>,TItem>

Specified by:

isSelected in class ComboBoxBase<MultiSelectComboBox<TItem>,TItem,Set<TItem>>

Parameters:

item - the item to check

Returns:

true if the item is selected, false otherwise

getSelectedItems

public Set<TItem> getSelectedItems()

Description copied from interface: MultiSelect

Returns an immutable set of the currently selected items. It is safe to invoke other SelectionModel methods while iterating over the set.

Implementation note: the iteration order of the items in the returned set should be well-defined and documented by the implementing class.

Specified by:

getSelectedItems in interface MultiSelect<MultiSelectComboBox<TItem>,TItem>

Returns:

the items in the current selection, not null

addSelectionListener

public Registration addSelectionListener(MultiSelectionListener<MultiSelectComboBox<TItem>,TItem> listener)

Description copied from interface: MultiSelect

Adds a selection listener that will be called when the selection is changed either by the user or programmatically.

Specified by:

addSelectionListener in interface MultiSelect<MultiSelectComboBox<TItem>,TItem>

Parameters:

listener - the value change listener, not null

Returns:

a registration for the listener

updateSelection

public void updateSelection(Set<TItem> addedItems,
                            Set<TItem> removedItems)

Description copied from interface: MultiSelect

Updates the selection by adding and removing the given items from it.

If all the added items were already selected and the removed items were not selected, this is a NO-OP.

Duplicate items (in both add and remove sets) are ignored.

Specified by:

updateSelection in interface MultiSelect<MultiSelectComboBox<TItem>,TItem>

Parameters:

addedItems - the items to add, not null

removedItems - the items to remove, not null

isSelectedItemsOnTop

public boolean isSelectedItemsOnTop()

Gets whether selected items are grouped at the top of the overlay.

Returns:

true if enabled, false otherwise

Since:

23.4

setSelectedItemsOnTop

public void setSelectedItemsOnTop(boolean selectedItemsOnTop)

Enables or disables grouping of the selected items at the top of the overlay.

Parameters:

selectedItemsOnTop - true to group selected items at the top

Since:

23.4

getAutoExpand

public MultiSelectComboBox.AutoExpandMode getAutoExpand()

Gets the behavior of the component when not all selected items can be displayed as chips within the current field width.

Returns:

The current MultiSelectComboBox.AutoExpandMode

Since:

23.4

setAutoExpand

public void setAutoExpand(MultiSelectComboBox.AutoExpandMode autoExpandMode)

Sets the behavior of the component when not all selected items can be displayed as chips within the current field width. Expansion only works with undefined size in the desired direction (i.e. setting `max-width` limits the component's width).

Since:

23.4

isKeepFilter

public boolean isKeepFilter()

Gets whether the filter is kept after selecting items. false by default.

Returns:

true if enabled, false otherwise

Since:

23.4

setKeepFilter

public void setKeepFilter(boolean keepFilter)

Enables or disables keeping the filter after selecting items. By default, the filter is cleared after selecting an item and the overlay shows the unfiltered list of items again. Enabling this option will keep the filter, which allows to select multiple filtered items in succession.

Parameters:

keepFilter - whether to keep the filter after selecting an item

Since:

23.4

getI18n

public MultiSelectComboBoxI18n getI18n()

Gets the internationalization object previously set for this component.

Note: updating the i18n object that is returned from this method will not update the component, unless it is set again using setI18n(MultiSelectComboBoxI18n)

Returns:

the i18n object. It will be null, if it has not been set previously

setI18n

public void setI18n(MultiSelectComboBoxI18n i18n)

Sets the internationalization properties for this component.

Parameters:

i18n - the internationalized properties, not null