com.vaadin.flow.component.combobox.

Class ComboBox<T>

    • Constructor Detail

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

        #setPageSize(int)}

      • 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

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

        setItems(Collection)

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

        HasItems.setItems(Object...)

    • Method Detail

      • setRenderer

        public void setRenderer(Renderer<T> renderer)

        Sets the TemplateRenderer responsible to render the individual items in the list of possible choices of the ComboBox. It doesn't affect how the selected item is rendered - that can be configured by using setItemLabelGenerator(ItemLabelGenerator).

        Parameters:

        renderer - a renderer for the items in the selection list of the ComboBox, not null Note that filtering of the ComboBox is not affected by the renderer that is set here. Filtering is done on the original values and can be affected by setItemLabelGenerator(ItemLabelGenerator).

      • setItems

        public void setItems(Collection<T> items)

        Sets the data items of this component provided as a collection.

        The provided collection instance may be used as-is. Subsequent modification of the collection might cause inconsistent data to be shown in the component unless it is explicitly instructed to read the data again.

        Filtering will use a case insensitive match to show all items where the filter text is a substring of the label displayed for that item, which you can configure with setItemLabelGenerator(ItemLabelGenerator).

        Filtering will be handled in the client-side if the size of the data set is less than the page size. To force client-side filtering with a larger data set (at the cost of increased network traffic), you can increase the page size with setPageSize(int).

        Setting the items creates a new DataProvider, which in turn resets the combo box's value to null. If you want to add and remove items to the current item set without resetting the value, you should update the previously set item collection and call getDataProvider().refreshAll().

        Specified by:

        setItems in interface HasItems<T>

        Parameters:

        items - the data items to display, not null

      • setItems

        public void setItems(ComboBox.ItemFilter<T> itemFilter,
                     Collection<T> items)

        Sets the data items of this combo box and a filtering function for defining which items are displayed when user types into the combo box.

        Note that defining a custom filter will force the component to make server roundtrips to handle the filtering. Otherwise it can handle filtering in the client-side, if the size of the data set is less than the pageSize.

        Setting the items creates a new DataProvider, which in turn resets the combo box's value to null. If you want to add and remove items to the current item set without resetting the value, you should update the previously set item collection and call getDataProvider().refreshAll().

        Parameters:

        itemFilter - filter to check if an item is shown when user typed some text into the ComboBox

        items - the data items to display

      • setItems

        public void setItems(ComboBox.ItemFilter<T> itemFilter,
                     T... items)

        Sets the data items of this combo box and a filtering function for defining which items are displayed when user types into the combo box.

        Note that defining a custom filter will force the component to make server roundtrips to handle the filtering. Otherwise it can handle filtering in the client-side, if the size of the data set is less than the pageSize.

        Setting the items creates a new DataProvider, which in turn resets the combo box's value to null. If you want to add and remove items to the current item set without resetting the value, you should update the previously set item collection and call getDataProvider().refreshAll().

        Parameters:

        itemFilter - filter to check if an item is shown when user typed some text into the ComboBox

        items - the data items to display

      • setDataProvider

        public void setDataProvider(DataProvider<T,String> dataProvider)

        Sets the data provider for this listing. The data provider is queried for displayed items as needed.

        The filter-type of the given data provider must be String so that it can handle the filters typed into the ComboBox by users. If your data provider uses some other type of filter, you can provide a function which converts the ComboBox's filter-string into that type via setDataProvider(DataProvider, SerializableFunction). Another way to do the same thing is to use this method with your data provider converted with DataProvider.withConvertedFilter(SerializableFunction).

        Changing the combo box's data provider resets its current value to null.

        Specified by:

        setDataProvider in interface HasFilterableDataProvider<T,String>

        Parameters:

        dataProvider - the data provider, not null

      • setDataProvider

        public <C> void setDataProvider(DataProvider<T,C> dataProvider,
                                SerializableFunction<String,C> filterConverter)

        Sets the data provider and filter converter for this listing. The data provider is queried for displayed items as needed.

        ComboBox triggers filtering queries based on the strings users type into the field. For this reason you need to provide the second parameter, a function which converts the filter-string typed by the user into filter-type used by your data provider. If your data provider already supports String as the filter-type, it can be used without a converter function via setDataProvider(DataProvider).

        Using this method provides the same result as using a data provider wrapped with DataProvider.withConvertedFilter(SerializableFunction).

        Changing the combo box's data provider resets its current value to null.

        Specified by:

        setDataProvider in interface HasFilterableDataProvider<T,String>

        Type Parameters:

        C - the filter type

        Parameters:

        dataProvider - the data provider, not null

        filterConverter - a function that converts filter values produced by this listing into filter values expected by the provided data provider, not null

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

        Parameters:

        attachEvent - the attach event

      • onDetach

        protected void onDetach(DetachEvent detachEvent)

        Description copied from class: Component

        Called when the component is detached from a UI.

        The default implementation does nothing.

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

        Overrides:

        onDetach in class Component

        Parameters:

        detachEvent - the detach event

      • setDataProvider

        public void setDataProvider(ListDataProvider<T> listDataProvider)

        Sets a list data provider as the data provider of this combo box.

        Filtering will use a case insensitive match to show all items where the filter text is a substring of the label displayed for that item, which you can configure with setItemLabelGenerator(ItemLabelGenerator).

        Filtering will be handled in the client-side if the size of the data set is less than the page size. To force client-side filtering with a larger data set (at the cost of increased network traffic), you can increase the page size with setPageSize(int).

        Changing the combo box's data provider resets its current value to null.

        Parameters:

        listDataProvider - the list data provider to use, not null

      • setDataProvider

        public void setDataProvider(ComboBox.ItemFilter<T> itemFilter,
                            ListDataProvider<T> listDataProvider)

        Sets a list data provider with an item filter as the data provider of this combo box. The item filter is used to compare each item to the filter text entered by the user.

        Note that defining a custom filter will force the component to make server roundtrips to handle the filtering. Otherwise it can handle filtering in the client-side, if the size of the data set is less than the pageSize.

        Changing the combo box's data provider resets its current value to null.

        Parameters:

        itemFilter - filter to check if an item is shown when user typed some text into the ComboBox

        listDataProvider - the list data provider to use, not null

      • getDataProvider

        public DataProvider<T,?> getDataProvider()

        Gets the data provider used by this ComboBox.

        Returns:

        the data provider used by this ComboBox

      • setItemLabelGenerator

        public void setItemLabelGenerator(ItemLabelGenerator<T> itemLabelGenerator)

        Sets the item label generator that is used to produce the strings shown in the combo box for each item. By default, String.valueOf(Object) is used.

        When the setRenderer(Renderer) is used, the ItemLabelGenerator is only used to show the selected item label.

        Parameters:

        itemLabelGenerator - the item label provider to use, not null

      • getItemLabelGenerator

        public ItemLabelGenerator<T> getItemLabelGenerator()

        Gets the item label generator that is used to produce the strings shown in the combo box for each item.

        Returns:

        the item label generator used, not null

      • setPageSize

        public void setPageSize(int pageSize)

        Sets the page size, which is the number of items requested at a time from the data provider. This does not guarantee a maximum query size to the backend; when the overlay has room to render more new items than the page size, multiple "pages" will be requested at once.

        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.

        Setting the page size after the ComboBox has been rendered effectively resets the component, and the current page(s) and sent over again.

        The default page size is 50.

        Parameters:

        pageSize - the maximum number of items sent per request, should be greater than zero

      • getPageSize

        public int getPageSize()

        Gets the page size, which is the number of items fetched at a time from the data provider.

        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.

        The default page size is 50.

        Returns:

        the maximum number of items sent per request

        See Also:

        #setPageSize(int)}

      • setOpened

        public void setOpened(boolean opened)

        Description copied from class: GeneratedVaadinComboBox

        Description copied from corresponding location in WebComponent:

        True if the dropdown is open, false otherwise.

        Overrides:

        setOpened in class GeneratedVaadinComboBox<ComboBox<T>,T>

        Parameters:

        opened - the boolean value to set

      • isOpened

        public boolean isOpened()

        Gets the states of the drop-down.

        Returns:

        true if the drop-down is opened, false otherwise

      • isInvalid

        public boolean isInvalid()

        Gets the validity of the combobox output.

        return true, if the value is invalid.

        Specified by:

        isInvalid in interface HasValidation

        Returns:

        the validity property from the component

      • getErrorMessage

        public String getErrorMessage()

        Gets the current error message from the combobox.

        Specified by:

        getErrorMessage in interface HasValidation

        Returns:

        the current error message

      • setAllowCustomValue

        public void setAllowCustomValue(boolean allowCustomValue)

        Enables or disables the component firing events for custom string input.

        When enabled, a CustomValueSetEvent will be fired when the user inputs a string value that does not match any existing items and commits it eg. by blurring or pressing the enter-key.

        Note that ComboBox doesn't do anything with the custom value string automatically. Use the addCustomValueSetListener(ComponentEventListener) method to determine how the custom value should be handled. For example, when the ComboBox has String as the value type, you can add a listener which sets the custom string as the value of the ComboBox with setValue(Object).

        Setting to true also allows an unfocused ComboBox to display a string that doesn't match any of its items nor its current value, unless this is explicitly handled with addCustomValueSetListener(ComponentEventListener). When set to false, an unfocused ComboBox will always display the label of the currently selected item.

        Overrides:

        setAllowCustomValue in class GeneratedVaadinComboBox<ComboBox<T>,T>

        Parameters:

        allowCustomValue - true to enable custom value set events, false to disable them

        See Also:

        addCustomValueSetListener(ComponentEventListener)

      • setAutoOpen

        public void setAutoOpen(boolean autoOpen)

        Enables or disables the dropdown opening automatically. If false the dropdown is only opened when clicking the toggle button or pressing Up or Down arrow keys.

        Parameters:

        autoOpen - false to prevent the dropdown from opening automatically

      • isAutoOpen

        public boolean isAutoOpen()

        Gets whether dropdown will open automatically or not.

        Returns:

        @{code true} if enabled, false otherwise

      • setAutofocus

        public void setAutofocus(boolean autofocus)

        Set the combobox to be input focused when the page loads.

        Overrides:

        setAutofocus in class GeneratedVaadinComboBox<ComboBox<T>,T>

        Parameters:

        autofocus - the boolean value to set

      • isAutofocus

        public boolean isAutofocus()

        Get the state for the auto-focus property of the combobox.

        This property is not synchronized automatically from the client side, so the returned value may not be the same as in client side.

        Returns:

        the autofocus property from the combobox

      • setPreventInvalidInput

        public void setPreventInvalidInput(boolean preventInvalidInput)

        Description copied from class: GeneratedVaadinComboBox

        Description copied from corresponding location in WebComponent:

        Set to true to prevent the user from entering invalid input.

        Overrides:

        setPreventInvalidInput in class GeneratedVaadinComboBox<ComboBox<T>,T>

        Parameters:

        preventInvalidInput - the boolean value to set

      • isPreventInvalidInput

        public boolean isPreventInvalidInput()

        Determines whether preventing the user from inputing invalid value.

        This property is not synchronized automatically from the client side, so the returned value may not be the same as in client side.

        Returns:

        the preventInvalidInput property of the combobox

      • setRequired

        public void setRequired(boolean required)

        Description copied from class: GeneratedVaadinComboBox

        Description copied from corresponding location in WebComponent:

        Set to true to mark the input as required.

        Overrides:

        setRequired in class GeneratedVaadinComboBox<ComboBox<T>,T>

        Parameters:

        required - the boolean value to set

      • isRequired

        public boolean isRequired()

        Determines whether the combobox is marked as input required.

        This property is not synchronized automatically from the client side, so the returned value may not be the same as in client side.

        Returns:

        true if the input is required, false otherwise

      • getLabel

        public String getLabel()

        Gets the label of the combobox.

        Specified by:

        getLabel in interface HasLabel

        Returns:

        the label property of the combobox

      • getPlaceholder

        public String getPlaceholder()

        Gets the placeholder of the combobox.

        Returns:

        the placeholder property of the combobox

      • getPattern

        public String getPattern()

        Gets the valid input pattern

        Returns:

        the pattern property of the combobox

      • addCustomValueSetListener

        public Registration addCustomValueSetListener(ComponentEventListener<GeneratedVaadinComboBox.CustomValueSetEvent<ComboBox<T>>> listener)

        Adds a listener for the event which is fired when user inputs a string value that does not match any existing items and commits it eg. by blurring or pressing the enter-key.

        Note that ComboBox doesn't do anything with the custom value string automatically. Use this method to determine how the custom value should be handled. For example, when the ComboBox has String as the value type, you can add a listener which sets the custom string as the value of the ComboBox with setValue(Object).

        As a side effect, this makes the ComboBox allow custom values. If you want to disable the firing of custom value set events once the listener is added, please disable it explicitly via the setAllowCustomValue(boolean) method.

        The custom value becomes disallowed automatically once the last custom value set listener is removed.

        Overrides:

        addCustomValueSetListener in class GeneratedVaadinComboBox<ComboBox<T>,T>

        Parameters:

        listener - the listener to be notified when a new value is filled

        Returns:

        a Registration for removing the event listener

        See Also:

        setAllowCustomValue(boolean)

      • setRequiredIndicatorVisible

        public void setRequiredIndicatorVisible(boolean requiredIndicatorVisible)

        Description copied from interface: HasValue

        Sets the required indicator visible or not.

        If set visible, it is visually indicated in the user interface.

        The method is intended to be used with Binder which does server-side validation. In case HTML element has its own (client-side) validation it should be disabled when setRequiredIndicatorVisible(true) is called and re-enabled back on setRequiredIndicatorVisible(false). It's responsibility of each component implementation to follow the contract so that the method call doesn't do anything else than show/hide the "required" indication. Usually components provide their own setRequired method which should be called in case the client-side validation is required.

        Specified by:

        setRequiredIndicatorVisible in interface HasValue<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>

        Specified by:

        setRequiredIndicatorVisible in interface HasValueAndElement<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>

        Parameters:

        requiredIndicatorVisible - true to make the required indicator visible, false if not

      • setClearButtonVisible

        public void setClearButtonVisible(boolean clearButtonVisible)

        Allows displaying a clear button in the combo box when a value is selected.

        The clear button is an icon, which can be clicked to set the combo box value to null.

        Overrides:

        setClearButtonVisible in class GeneratedVaadinComboBox<ComboBox<T>,T>

        Parameters:

        clearButtonVisible - true to display the clear button, false to hide it

      • isClearButtonVisible

        public boolean isClearButtonVisible()

        Gets whether this combo box displays a clear button when a value is selected.

        Returns:

        true if this combo box displays a clear button, false otherwise

        See Also:

        setClearButtonVisible(boolean)

      • validate

        protected void validate()

        Description copied from class: GeneratedVaadinComboBox

        Description copied from corresponding location in WebComponent:

        Returns true if value is valid, and sets the invalid flag appropriately.

        This function is not supported by Flow because it returns a boolean. Functions with return types different than void are not supported at this moment.

        Overrides:

        validate in class GeneratedVaadinComboBox<ComboBox<T>,T>

      • addValidationStatusChangeListener

        public Registration addValidationStatusChangeListener(ValidationStatusChangeListener<T> listener)

        Description copied from interface: HasValidator

        Enables the implementing components to notify changes in their validation status to the observers.

        Note: This method can be overridden by the implementing classes e.g. components, to enable the associated Binder.Binding instance subscribing for their validation change events and revalidate itself.

        This method primarily designed for notifying the Binding about the validation status changes of a bound component at the client-side. WebComponents such as <vaadin-date-picker> or any other component that accept a formatted text as input should be able to communicate their invalid status to their server-side instance, and a bound server-side component instance must notify its binding about this validation status change as well. When the binding instance revalidates, a chain of validators and convertors get executed one of which is the default validator provided by HasValidator.getDefaultValidator(). Thus, In order for the binding to be able to show/clear errors for its associated bound field, it is important that implementing components take that validation status into account while implementing any validator and converter including HasValidator.getDefaultValidator(). Here is an example: 

         @Tag("date-picker-demo")
 public class DatePickerDemo implements HasValidator<LocalDate> {

     // Each web component has a way to communicate its validation status
     // to its server-side component instance. The following clientSideValid
     // state is introduced here just for the sake of simplicity of this code
     // snippet:
     boolean clientSideValid = true;

     /**
      * Note how clientSideValid engaged in the definition
      * of this method. It is important to reflect this status either
      * in the returning validation result of this method or any other
      * validation that is associated with this component.
      */
     @Override
     public Validator getDefaultValidator() {
          return (value, valueContext) -> clientSideValid ? ValidationResult.ok()
                 : ValidationResult.error("Invalid date format");
     }

     private final Collection<ValidationStatusChangeListener<LocalDate>>
         validationStatusListeners = new ArrayList<>();

     /**
      * This enables the binding to subscribe for the validation status
      * change events that are fired by this component and revalidate
      * itself respectively.
      */
     @Override
     public Registration addValidationStatusChangeListener(
             ValidationStatusChangeListener<LocalDate> listener) {
         validationStatusListeners.add(listener);
         return () -> validationStatusListeners.remove(listener);
     }

     private void fireValidationStatusChangeEvent(
             boolean newValidationStatus) {
         if (this.clientSideValid != newValidationStatus) {
             this.clientSideValid = newValidationStatus;
             var event = new ValidationStatusChangeEvent<>(this,
                     newValidationStatus);
             validationStatusListeners.forEach(
                     listener -> listener.validationStatusChanged(event));
         }
     }
 }

        Specified by:

        addValidationStatusChangeListener in interface HasValidator<T>

        Returns:

        Registration of the added listener.

        See Also:

        Binder.BindingBuilderImpl.bind(ValueProvider, Setter)

      • isEnforcedFieldValidationEnabled

        protected boolean isEnforcedFieldValidationEnabled()