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:
com.vaadin.flow.component.AttachNotifier, com.vaadin.flow.component.BlurNotifier<MultiSelectComboBox<TItem>>, com.vaadin.flow.component.DetachNotifier, com.vaadin.flow.component.Focusable<MultiSelectComboBox<TItem>>, com.vaadin.flow.component.FocusNotifier<MultiSelectComboBox<TItem>>, com.vaadin.flow.component.HasAriaLabel, com.vaadin.flow.component.HasElement, com.vaadin.flow.component.HasEnabled, com.vaadin.flow.component.HasHelper, com.vaadin.flow.component.HasLabel, com.vaadin.flow.component.HasPlaceholder, com.vaadin.flow.component.HasSize, com.vaadin.flow.component.HasStyle, com.vaadin.flow.component.HasTheme, com.vaadin.flow.component.HasValidation, com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>, com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>, HasAllowedCharPattern, HasAutoOpen, HasClearButton, HasClientValidation, HasOverlayClassName, HasThemeVariant<MultiSelectComboBoxVariant>, HasTooltip, HasValidationProperties, InputField<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>, com.vaadin.flow.data.binder.HasValidator<Set<TItem>>, com.vaadin.flow.data.provider.HasDataView<TItem,String,ComboBoxDataView<TItem>>, com.vaadin.flow.data.provider.HasLazyDataView<TItem,String,ComboBoxLazyDataView<TItem>>, com.vaadin.flow.data.provider.HasListDataView<TItem,ComboBoxListDataView<TItem>>, com.vaadin.flow.data.selection.MultiSelect<MultiSelectComboBox<TItem>,TItem>, Serializable
@Tag("vaadin-multi-select-combo-box") @NpmPackage(value="@vaadin/polymer-legacy-adapter",version="24.5.3") @NpmPackage(value="@vaadin/multi-select-combo-box",version="24.5.3") @JsModule("@vaadin/polymer-legacy-adapter/style-modules.js") @JsModule("@vaadin/multi-select-combo-box/src/vaadin-multi-select-combo-box.js") @JsModule("./flow-component-renderer.js") @JsModule("./comboBoxConnector.js") public class MultiSelectComboBox<TItem> extends ComboBoxBase<MultiSelectComboBox<TItem>,TItem,Set<TItem>> implements com.vaadin.flow.data.selection.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.

Validation

MultiSelectComboBox comes with a built-in validation mechanism that verifies that the field is not empty when required is enabled.

Validation is triggered whenever the user initiates a value change, for example by selection from the dropdown or manual entry followed by Enter or blur. Programmatic value changes trigger validation as well. If validation fails, the component is marked as invalid and an error message is displayed below the input.

The required error message can be configured using either MultiSelectComboBoxI18n.setRequiredErrorMessage(String) or HasValidationProperties.setErrorMessage(String).

For more advanced validation that requires custom rules, you can use Binder. Please note that Binder provides its own API for the required validation, see asRequired().

However, if Binder doesn't fit your needs and you want to implement fully custom validation logic, you can disable the built-in validation by setting ComboBoxBase.setManualValidation(boolean) to true. This will allow you to control the invalid state and the error message manually using HasValidationProperties.setInvalid(boolean) and HasValidationProperties.setErrorMessage(String) API.

Author:
Vaadin Ltd
See Also:

  • Constructor Details

    • 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:

    • 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:

    • 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(com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.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, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.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, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.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 Details

    • onAttach

      protected void onAttach(com.vaadin.flow.component.AttachEvent attachEvent)
      Overrides:
      onAttach in class ComboBoxBase<MultiSelectComboBox<TItem>,TItem,Set<TItem>>

    • setRequiredIndicatorVisible

      public void setRequiredIndicatorVisible(boolean required)
      Sets whether the user is required to provide a value. When required, an indicator appears next to the label and the field invalidates if the value is cleared.

      NOTE: The required indicator is only visible when the field has a label, see HasLabel.setLabel(String).

      Specified by:
      setRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>
      Specified by:
      setRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>
      Overrides:
      setRequiredIndicatorVisible in class ComboBoxBase<MultiSelectComboBox<TItem>,TItem,Set<TItem>>
      Parameters:
      required - true to make the field required, false otherwise
      See Also:

    • isRequiredIndicatorVisible

      public boolean isRequiredIndicatorVisible()
      Gets whether the user is required to provide a value.
      Specified by:
      isRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>
      Specified by:
      isRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>
      Overrides:
      isRequiredIndicatorVisible in class ComboBoxBase<MultiSelectComboBox<TItem>,TItem,Set<TItem>>
      Returns:
      true if the field is required, false otherwise
      See Also:

    • 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 com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>
      Specified by:
      getValue in interface com.vaadin.flow.data.selection.MultiSelect<MultiSelectComboBox<TItem>,TItem>
      Overrides:
      getValue in class com.vaadin.flow.component.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 com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<MultiSelectComboBox<TItem>,Set<TItem>>,Set<TItem>>
      Specified by:
      setValue in interface com.vaadin.flow.data.selection.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 com.vaadin.flow.data.selection.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()
      Specified by:
      getSelectedItems in interface com.vaadin.flow.data.selection.MultiSelect<MultiSelectComboBox<TItem>,TItem>

    • addSelectionListener

      public com.vaadin.flow.shared.Registration addSelectionListener(com.vaadin.flow.data.selection.MultiSelectionListener<MultiSelectComboBox<TItem>,TItem> listener)
      Specified by:
      addSelectionListener in interface com.vaadin.flow.data.selection.MultiSelect<MultiSelectComboBox<TItem>,TItem>

    • updateSelection

      public void updateSelection(Set<TItem> addedItems, Set<TItem> removedItems)
      Specified by:
      updateSelection in interface com.vaadin.flow.data.selection.MultiSelect<MultiSelectComboBox<TItem>,TItem>

    • 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:
      24.3

    • 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:
      24.3

    • isSelectedItemsOnTop

      public boolean isSelectedItemsOnTop()
      Gets whether selected items are grouped at the top of the overlay.
      Returns:
      true if enabled, false otherwise
      Since:
      24.3

    • 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:
      24.3

    • isKeepFilter

      public boolean isKeepFilter()
      Gets whether the filter is kept after selecting items. false by default.
      Returns:
      true if enabled, false otherwise
      Since:
      24.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

    • getI18n

      public MultiSelectComboBoxI18n getI18n()
      Gets the internationalization object previously set for this component.

      NOTE: Updating the instance that is returned from this method will not update the component if not set again using setI18n(MultiSelectComboBoxI18n)

      Overrides:
      getI18n in class ComboBoxBase<MultiSelectComboBox<TItem>,TItem,Set<TItem>>
      Returns:
      the i18n object or null if no i18n object has been set

    • setI18n

      public void setI18n(MultiSelectComboBoxI18n i18n)
      Sets the internationalization object for this component.
      Parameters:
      i18n - the i18n object, not null

    • setOverlayWidth

      public void setOverlayWidth(String width)
      Sets the dropdown overlay width.
      Parameters:
      width - the new dropdown width. Pass in null to set the dropdown width back to the default value.

    • setOverlayWidth

      public void setOverlayWidth(float width, com.vaadin.flow.component.Unit unit)
      Sets the dropdown overlay width. Negative number implies unspecified size (the dropdown width is reverted back to the default value).
      Parameters:
      width - the width of the dropdown.
      unit - the unit used for the dropdown.