Package com.vaadin.flow.component.combobox

Class ComboBox<T>

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.AbstractField<ComboBox<T>,T>
com.vaadin.flow.component.AbstractSinglePropertyField<ComboBox<T>,T>
com.vaadin.flow.component.combobox.ComboBoxBase<ComboBox<T>,T,T>
com.vaadin.flow.component.combobox.ComboBox<T>
Type Parameters:
T - 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<ComboBox<T>>, com.vaadin.flow.component.DetachNotifier, com.vaadin.flow.component.Focusable<ComboBox<T>>, com.vaadin.flow.component.FocusNotifier<ComboBox<T>>, 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<ComboBox<T>,T>,T>, com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>, com.vaadin.flow.component.shared.HasAllowedCharPattern, com.vaadin.flow.component.shared.HasAutoOpen, com.vaadin.flow.component.shared.HasClearButton, com.vaadin.flow.component.shared.HasPrefix, com.vaadin.flow.component.shared.HasThemeVariant<ComboBoxVariant>, com.vaadin.flow.component.shared.HasTooltip, com.vaadin.flow.component.shared.HasValidationProperties, com.vaadin.flow.component.shared.InputField<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>, com.vaadin.flow.data.binder.HasValidator<T>, com.vaadin.flow.data.provider.HasDataView<T,String,ComboBoxDataView<T>>, com.vaadin.flow.data.provider.HasLazyDataView<T,String,ComboBoxLazyDataView<T>>, com.vaadin.flow.data.provider.HasListDataView<T,ComboBoxListDataView<T>>, Serializable
@Tag("vaadin-combo-box") @NpmPackage(value="@vaadin/combo-box", version="25.0.0-beta5") @JsModule("@vaadin/combo-box/src/vaadin-combo-box.js") @JsModule("./flow-component-renderer.js") @JsModule("./comboBoxConnector.js") public class ComboBox<T> extends ComboBoxBase<ComboBox<T>,T,T> implements com.vaadin.flow.component.shared.HasPrefix, com.vaadin.flow.component.shared.HasThemeVariant<ComboBoxVariant>
Combo Box allows the user to choose a value from a filterable list of options presented in an overlay.

ComboBox 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).

ComboBox can do filtering either in the browser or in the server. When ComboBox 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(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

Combo Box 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 ComboBox.ComboBoxI18n.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:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    ComboBox.ComboBoxI18n
    The internationalization properties for ComboBox.
    static interface 
    ComboBox.FetchItemsCallback<T>
    A callback method for fetching items.
    static interface 
    ComboBox.ItemFilter<T>
    Predicate to check ComboBox items against user typed strings.

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

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

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

    com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<C extends com.vaadin.flow.component.Component,V>

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

    com.vaadin.flow.component.BlurNotifier.BlurEvent<C extends com.vaadin.flow.component.Component>

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

    com.vaadin.flow.component.FocusNotifier.FocusEvent<C extends com.vaadin.flow.component.Component>

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

    com.vaadin.flow.component.HasValue.ValueChangeEvent<V>, com.vaadin.flow.component.HasValue.ValueChangeListener<E extends com.vaadin.flow.component.HasValue.ValueChangeEvent<?>>

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    T
    getEmptyValue()
     
    ComboBox.ComboBoxI18n
    getI18n()
    Gets the internationalization object previously set for this component.
    String
    getPattern()
    The pattern to validate the input with
    protected boolean
    isSelected(T item)
    Whether the item is currently selected in the combo box.
    protected void
    refreshValue()
    Refresh value / selection of the web component after changes that might affect the presentation / rendering of items
    void
    setI18n(ComboBox.ComboBoxI18n i18n)
    Sets the internationalization object for this component.
    void
    setOverlayWidth(float width, com.vaadin.flow.component.Unit unit)
    Sets the dropdown overlay width.
    void
    setOverlayWidth(String width)
    Sets the dropdown overlay width.
    void
    setPattern(String pattern)
    Sets the pattern with which to validate the input
    void
    setRequiredIndicatorVisible(boolean required)
    Sets whether the user is required to provide a value.

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

    addCustomValueSetListener, generateClassName, generateLabel, getAriaLabel, getAriaLabelledBy, getDataCommunicator, getDataController, getDataGenerator, getDataProvider, getDefaultValidator, getFilter, getGenericDataView, getItemClassNameGenerator, getItemLabelGenerator, getKeyMapper, getLazyDataView, getListDataView, getPageSize, getRenderManager, isAllowCustomValue, isAutofocus, isOpened, isRequired, isRequiredIndicatorVisible, onAttach, onDetach, runBeforeClientResponse, setAllowCustomValue, setAriaLabel, setAriaLabelledBy, setAutofocus, setClassNameGenerator, setDataProvider, setDataProvider, setFilter, setI18n, setItemLabelGenerator, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItemsPageable, setItemsPageable, setItemsWithFilterConverter, setItemsWithFilterConverter, setManualValidation, setOpened, setPageSize, setRenderer, setRequired, setValue, validate

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

    getSynchronizationRegistration, hasValidValue, setPresentationValue, setSynchronizedEvent

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

    addValueChangeListener, getValue, 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, removeFromParent, scrollIntoView, 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.HasAutoOpen

    isAutoOpen, setAutoOpen

    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.HasPlaceholder

    getPlaceholder, setPlaceholder

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

    getPrefixComponent, setPrefixComponent

    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, setThemeVariant, setThemeVariants, setThemeVariants

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

    getTooltip, setTooltipMarkdown, setTooltipText

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

    getErrorMessage, isInvalid, setErrorMessage, setInvalid

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

    addValidationStatusChangeListener

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

    addValueChangeListener, clear, getOptionalValue, getValue, isEmpty

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

    isReadOnly, setReadOnly

  • Constructor Details

    • ComboBox

      public ComboBox(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:

    • ComboBox

      public ComboBox()
      Default constructor. Creates an empty combo box.

    • ComboBox

      public ComboBox(String label)
      Creates an empty combo box with the defined label.
      Parameters:
      label - the label describing the combo box
      See Also:
      • HasLabel.setLabel(String)

    • ComboBox

      public ComboBox(String label, Collection<T> 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:

    • ComboBox

      @SafeVarargs public ComboBox(String label, T... 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...)

    • ComboBox

      public ComboBox(com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>> listener)
      Constructs a combo box with a value change listener.
      Parameters:
      listener - the value change listener to add
      See Also:
      • AbstractField.addValueChangeListener(ValueChangeListener)

    • ComboBox

      public ComboBox(String label, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>> 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)

    • ComboBox

      @SafeVarargs public ComboBox(String label, com.vaadin.flow.component.HasValue.ValueChangeListener<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>> listener, T... 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

    • setRequiredIndicatorVisible

      public void setRequiredIndicatorVisible(boolean required)
      Description copied from class: ComboBoxBase
      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<ComboBox<T>,T>,T>
      Specified by:
      setRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>
      Overrides:
      setRequiredIndicatorVisible in class ComboBoxBase<ComboBox<T>,T,T>
      Parameters:
      required - true to make the field required, false otherwise
      See Also:

    • getPattern

      public String getPattern()
      The pattern to validate the input with
      Returns:
      the pattern to validate the input with

    • setPattern

      public void setPattern(String pattern)
      Sets the pattern with which to validate the input
      Parameters:
      pattern - the pattern to validate the input with

    • 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<ComboBox<T>,T,T>

    • isSelected

      protected boolean isSelected(T item)
      Description copied from class: ComboBoxBase
      Whether the item is currently selected in the combo box.
      Specified by:
      isSelected in class ComboBoxBase<ComboBox<T>,T,T>
      Parameters:
      item - the item to check
      Returns:
      true if the item is selected, false otherwise

    • getEmptyValue

      public T getEmptyValue()
      Specified by:
      getEmptyValue in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>
      Overrides:
      getEmptyValue in class com.vaadin.flow.component.AbstractField<ComboBox<T>,T>

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

    • getI18n

      public ComboBox.ComboBoxI18n 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(ComboBoxI18n)

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

    • setI18n

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